From: sunil.unnava Date: Thu, 25 Apr 2019 21:41:10 +0000 (-0400) Subject: add swagger API to documentation X-Git-Tag: 1.1.14~8 X-Git-Url: https://gerrit.onap.org/r/gitweb?a=commitdiff_plain;h=23f58b6aecad96d2129956b683cf5c039634d5a9;p=dmaap%2Fmessagerouter%2Fmessageservice.git add swagger API to documentation Issue-ID: DMAAP-922 Change-Id: I44916797377a0d19246245817d8339f47b5e5a50 Signed-off-by: sunil.unnava --- diff --git a/docs/offeredapis/api.rst b/docs/offeredapis/api.rst new file mode 100644 index 0000000..0428850 --- /dev/null +++ b/docs/offeredapis/api.rst @@ -0,0 +1,535 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Offered APIs +~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 3 + +DMaaP Message Router utilizes an HTTP REST API to service all Publish +and Consume transactions. HTTP and REST standards are followed so +clients as varied as CURL, Java applications and even Web Browsers will +work to interact with Message Router.Message Router uses AAF for user's +authentication and authorization. + +General HTTP Requirements +------------------------- + +A DMaaP Message Router transactions consists of 4 distinct segments, +HTTP URL, HTTP Header, HTTP Body (POST) and HTTP Response. The general +considerations for each segment are as follows and are required for each +of the specific transactions described in this section. + +HTTP URL +------- + +http[s]://serverBaseURL{/routing}{resourcePath} + +- The serverBaseURL points to DMaaP Message Router host/port that will service the request. + +- The resourcePath specifies the specific service, or Topic, that the client is attempting to reach + +HTTP Header +----------- + +Specifies HTTP Headers, such as Content-Type, that define the parameters +of the HTTP Transaction + +HTTP Body +--------- + +The HTTP Body contains the topic content when Publishing or Consuming. +The Body may contain topic messages in several formats (like below) but +it must be noted, that, except in very specific circumstances, messages +are not inspected for content. + + ++-------------------------+-----------------------------------------------------------------------------------------------------------------+ +| Content-Type | Description | ++=========================+=================================================================================================================+ +| text/plain | Each line in the POST body is treated as a separate message. No partition key is specified, and therefore no | +| | order is guaranteed. This format is mainly for test, as messages are highly likely to be re-ordered when | +| | delivered through the Kafka cluster. | ++-------------------------+-----------------------------------------------------------------------------------------------------------------+ +| application/json | The payload maybe a single JSON object or a JSON array of JSON objects. Each object is handled as an individual | +| | message..Note that use of this format may result in equivalent but altered JSON objects sent to consumers. | +| | That's because MR uses a standard JSON parser to read each object into memory before pushing the object to the | +| | Kafka system. At that point, the JSON object is re-written from the in-memory object. This can result in | +| | re-ordered fields or changes in whitespace. If you want to preserve JSON objects exactly, | +| | use application/cambria. Recommended to follow the JSON format. | ++-------------------------+-----------------------------------------------------------------------------------------------------------------+ + +Publishers +----------- + +**Description**:Publishes data to Kafka server on the topic mentioned in the URL. +Messages will be in the request body + +The MessageRouter service has no requirements on what publishers can put +onto a topic. The messages are opaque to the service and are treated as +raw bytes. In general, passing JSON messages is preferred, but this is +due to higher-level features and related systems, not the MessageRouter +broker itself. + +Request URL +=========== + +POST http(s)://{HOST:PORT}/events/{topicname} + +Request Parameters +================== + ++--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+ +| Name | Description | Param Type | Data type | Max Len | Required | Format | Valid/EXample values | ++====================+==============================+==================+============+===========+=============+================================+=============================+ +| Topicname | topic name to be posted | Path | String | 40 | Y | | org.onap.dmaap.mr.testtopic | ++--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+ +| content-type | To specify type of message | Header | String | 20 | N | | application/json | ++--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+ +| Username | userid | Header | String | | N | Basic Authentication Header | | ++--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+ +| Password | | Header | String | | N | Basic Authentication Header | | ++--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+ +| partitionKey | | QueryParam | String | | N | String value | ?Partitionkey=123 | ++--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+ + +**NOTE**: To publish data to the authenticated topic, Publisher must + have the AAF permission org.onap.dmaap.mr.topic|:topic.|pub. +Publishers may use DMaaP BusController for provisoning the AAF permissions + +Response Parameters +=================== + ++------------------+------------------------+------------+--------------+------------------------------+ +| Name | Description | Type | Format | Valid/Example Values | ++==================+========================+============+==============+==============================+ +| httpStatusCode | | | | 200, 201 etc. | ++------------------+------------------------+------------+--------------+------------------------------+ +| mrErrorCode | Numeric error code | | | 200, 201 etc. | ++------------------+------------------------+------------+--------------+------------------------------+ +| errorMessage | | | | SUCCESS, or error message. | ++------------------+------------------------+------------+--------------+------------------------------+ +| helpURL | helpurl | | | | ++------------------+------------------------+------------+--------------+------------------------------+ +| transactionid | transaction-id value | | | | ++------------------+------------------------+------------+--------------+------------------------------+ + + + +Response /Error Codes +===================== + ++---------------------------+------------------------------------+ +| Response statusCode | Response statusMessage | ++===========================+====================================+ +| 200-299 | Success | ++---------------------------+------------------------------------+ +| 400-499 | the client request has a problem | ++---------------------------+------------------------------------+ +| 500-599 | the DMaaP service has a problem | ++---------------------------+------------------------------------+ + ++------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+ +| Error code | HTTPCode | Description | Issue Reason | ++========================+===============+=================================+=========================================================================================================+ +| DMaaP\_MR\_ERR\_3001 | 413 | Request Entity too large | Message size exceeds the batch limit .Reduce the batch size and try again | ++------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+ +| DMaaP\_MR\_ERR\_3002 | 500 | Internal Server Error | Unable to publish messages. Please contact administrator | ++------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+ +| DMaaP\_MR\_ERR\_3003 | 400 | Bad Request | Incorrect Batching format. Please correct the batching format and try again | ++------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+ +| DMaaP\_MR\_ERR\_3004 | 413 | Request Entity too large | Message size exceeds the message size limit .Reduce the message size and try again | ++------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+ +| DMaaP\_MR\_ERR\_3005 | 400 | Bad Request | Incorrect JSON object. Please correct the JSON format and try again | ++------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+ +| DMaaP\_MR\_ERR\_3006 | 504 | Network Connect Timeout Error | Connection to the DMaaP MR was timed out.Please try again | ++------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+ +| DMaaP\_MR\_ERR\_3007 | 500 | Internal Server Error | Failed to publish messages to topic . Successfully published number of messages. | ++------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+ + +Sample Request: +=============== + ++-----------------------------------------------------------------------------------+ +| POST | +| | +| *Payload-* *{"message":"message description"}* *Content-Type: application/json* | +| | +| Example: | +| | +| curl -u XXXX@abc.com:X -H 'Content-Type:text/plain' -X POST -d @sampleMsg.txt | +| | +| { "count": 1, | +| | +| "serverTimeMs": 19" | +| | +| } | ++-----------------------------------------------------------------------------------+ + +Sample Response: +================ + ++---------------------------------------------------------------------+ +| HTTP/1.1 200 OK | +| | +| Server: Apache-Coyote/1.1 | +| | +| transactionId: 28-12-2015::08:18:50:682::::28122015552391 | +| | +| Content-Type: application/json | +| | +| Content-Length: 42 | +| | +| Date: Mon, 28 Dec 2015 13:18:50 GMT | ++---------------------------------------------------------------------+ + + + +Subscribers +----------- +**Description**:To subscribe to a MessageRouter topic, a subscriber issues a GET to the RESTful HTTP endpoint for events. + +Request URL: +============ + +GET http(s)://{HOST:PORT}}/events/{topicname}/{consumegroup}/{consumerid}/{timeout=x} + +Request Parameters: +=================== + ++--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+ +| Name | Description | Param Type | data type | MaxLen | Required | Format | Valid/Example Values | ++==============+=================================+==================+============+==============+=============+=====================+========================+ +| Topicname | topic name to be posted | Path | String | 40 | Y | | | ++--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+ +| Consumer | A name that uniquely identifies | Path | String | | Y | | CG1 | +| group | your subscribers | | | | | | | ++--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+ +| consumerId | Within your subscribers group, | Path | String | | Y | | C1 | +| | a name that uniquely identifies | | | | | | | +| | your subscribers process | | | | | | | ++--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+ +| content-type | To specify type of message | Header | String | 20 | N | | aplication/json | +| | content(json,text or cambria) | | | | | | | ++--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+ +| Username | userid | Header | String | 1 | N | | | ++--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+ +| Password | | Header | String | 1 | N | | | ++--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+ + +**NOTE**:To read data from a authenticated topic, User must have the +AAF permission org.onap.dmaap.mr.topic|:topic.|sub. +Subscribers may use DMaaP BusController for provisoning the permissions in AAF + +Response Parameters: +==================== + ++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ +| Name | Description | Type | Format | Valid/Example Values | ++==================+================================+============+==============+===========================================================+ +| httpStatusCode | | | | 200, 201 etc. | ++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ +| mrErrorCode | Numeric error code | | | 200, 201 etc. | ++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ +| errorMessage | | | | SUCCESS, or error message. | ++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ +| helpURL | helpurl | | | | ++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ +| tranactionid | transaction-id value | | | 28-12-2015::08:18:50:682::135.25.227.66::28122015552391 | ++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ +| ResponseBody | Messages consumed from topic | Json | Json | | ++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ + + +Response /Error Codes +===================== + + ++---------------------------+------------------------------------+ +| Response statusCode | Response statusMessage | ++===========================+====================================+ +| 200-299 | Success | ++---------------------------+------------------------------------+ +| 400-499 | the client request has a problem | ++---------------------------+------------------------------------+ +| 500-599 | the DMaaP service has a problem | ++---------------------------+------------------------------------+ + ++-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+ +| Error code | HTTPCode | Description | Issue Reason | ++=========================+=================+============================+=============================================================================================+ +| DMaaP\_MR\_ERR\_3008 | 413 | Request Entity too large | Message size exceeds the batch limit .Reduce the batch size and try again | ++-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+ +| DMaaP\_MR\_ERR\_3009 | 500 | Internal Server Error | Unable to publish messages. Please contact administrator | ++-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+ +| DMaaP\_MR\_ERR\_3010 | 400 | Bad Request | Incorrect Batching format. Please correct the batching format and try again | ++-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+ +| DMaaP\_MR\_ERR\_3011 | 413 | Request Entity too large | Message size exceeds the message size limit .Reduce the message size and try again | ++-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+ +| DMaaP\_MR\_ERR\_5012 | 429 | Too many requests | This client is making too many requests. Please use a long poll setting to decrease the | +| | | | number of requests that result in empty responses. | ++-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+ +| | 503 | Service Unavailable | Service Unavailable. | ++-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+ + +Sample Request: +=============== + ++----------------------------------------------------------------------------------------------------+ +| GET http://:3904/events/com.att.dmaap.mr.sprint/mygroup/mycus | +| | +| Content-Type: application/json | +| | +| Example: | +| | +|curl -u XXX@csp.abc.com:MRDmap2016$ -X GET -d 'MyfirstMessage' | +| | +|http://mrlocal00.dcae.proto.research.att.com:3904/events/com.att.ecomp_test.crm.preDeo/myG/C1 | +| | +|[I am r sending first msg,I am R sending first msg] | ++----------------------------------------------------------------------------------------------------+ + +Provisioning +------------ +**Description**: To create , modify or delete the MessageRouter topics.These APIs can also be used by other applications to provision topics in MessageRouter. +DMaaP BusController is recommended for topic and AAf permissions provisoning + +Create Topic +============ +Request URL: +============ + +POST http(s)://{HOST:PORT}/topics/create + +Request Parameters: +=================== + ++-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+ +| Name | Description | Param Type | datatype | MaxLen | Required | Format | Valid/Example Values | ++===================+=================================+==================+============+==============+=============+=============+===================================+ +| Topicname | topicname to be created in MR | Body | String | 20 | Y | Json | org.onap.dmaap.mr.metrics | ++-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+ +| topicDescription | description for topic | Body | String | 15 | Y | | | ++-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+ +| partitionCount | Kafka topic partition | Body | String | 1 | Y | | | ++-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+ +| replicationCount | Kafka topic replication | Body | String | 1 | Y | | 3 (Default -for 3 node Kafka ) | ++-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+ +| transaction | to create transaction id for | Body | Boolean | 1 | N | | true | +| Enabled | each message transaction | | | | | | | ++-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+ +| Content-Type | application/json | Header | String | | | | application/json | ++-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+ + +**NOTE**:To Create a authenticated topic, user must have the AAF permission + org.onap.dmaap.mr.topicFactory|:org.onap.dmaap.mr.topic:org.onap.dmaap.mr|create + + ++---------------------------+------------------------------------+ +| Response statusCode | Response statusMessage | ++===========================+====================================+ +| 200-299 | Success | ++---------------------------+------------------------------------+ +| 400-499 | the client request has a problem | ++---------------------------+------------------------------------+ +| 500-599 | the DMaaP service has a problem | ++---------------------------+------------------------------------+ + + ++-------------------------+-----------------+--------------------------------------------------+ +| Error code | HTTP Code | Description | ++=========================+=================+==================================================+ +| DMaaP\_MR\_ERR\_5001 | 500 | Failed to retrieve list of all topics | ++-------------------------+-----------------+--------------------------------------------------+ +| DMaaP\_MR\_ERR\_5002 | 500 | Failed to retrieve details of topic: | ++-------------------------+-----------------+--------------------------------------------------+ +| DMaaP\_MR\_ERR\_5003 | 500 | Failed to create topic: | ++-------------------------+-----------------+--------------------------------------------------+ +| DMaaP\_MR\_ERR\_5004 | 500 | Failed to delete topic: | ++-------------------------+-----------------+--------------------------------------------------+ + + +Response Parameters +==================== + ++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ +| Name | Description | Type | Format | Valid/Example Values | ++==================+================================+============+==============+===========================================================+ +| httpStatusCode | | | | 200, 201 etc. | ++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ +| mrErrorCode | Numeric error code | | | 5005 | ++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ +| errorMessage | | | | SUCCESS, or error message. | ++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ +| helpURL | helpurl | | | | ++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ +| ResponseBody | Topic details (owner, | Json | Json | | +| | trxEnabled=true) | | | | ++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ + + +Sample Request: +=============== + + .. code:: bash + + POST http://:3904/topic/create + Request Body + {"topicName":"org.onap.dmaap.mr.testtopic","description":"This is a test Topic ", + "partitionCount":"1","replicationCount":"3","transactionEnabled":"true"} + Content-Type: application/json + Example: + curl -u XXXc@csp.abc.com:xxxxx$ -H 'Content-Type:application/json' -X POST -d + @topicname.txt http://message-router:3904/topics/create + { + "writerAcl": { + "enabled": false, + "users": [] + }, + "description": "This is a TestTopic", + "name": "org.onap.dmaap.mr.testtopic", + "readerAcl": { + "enabled": false, + "users": [] + + +GetTopic Details +---------------- + +Request URL +=========== + +GET http(s)://{HOST:PORT}/topics : To list the details of all the topics in Message Router. + +GET http(s)://{HOST:PORT}/topics/{topicname} : To list the details of specified topic . + +Request Parameters +================== + ++--------------------------+-------------------------+------------------+------------+-----------+-------------+-----------------+-----------------------------+ +| Name | Description | Param Type | Data type | Max Len | Required | Format | Valid/EXample values | ++==========================+=========================+==================+============+===========+=============+=================+=============================+ +| Topicname | topic name details | Body | String | 20 | Y | Json | org.onap.dmaap.mr.testtopic | ++--------------------------+-------------------------+------------------+------------+-----------+-------------+-----------------+-----------------------------+ + +**NOTE**:To view a authenticated topic, user must have the AAF permission + org.onap.dmaap.mr.topic|*|view + + +Response Parameters +==================== + ++------------------+------------------------+------------+----------+---------+----------------------------+ +| Name | Description | ParamType | datatype |Format | Valid/Example Values | ++==================+========================+============+==========+=========+============================+ +| topicname | topic name details | Body | String | Json | org.onap.dmaap.mr.testopic | ++------------------+------------------------+------------+----------+---------+----------------------------+ +| description | | | String | | | ++------------------+------------------------+------------+----------+---------+----------------------------+ +| owner |user id who created the | | | | | +| | topic | | | | | ++------------------+------------------------+------------+----------+---------+----------------------------+ +| txenabled | true or false | | boolean | | | ++------------------+------------------------+------------+----------+---------+----------------------------+ + ++---------------------------+------------------------------------+ +| Response statusCode | Response statusMessage | ++===========================+====================================+ +| 200-299 | Success | ++---------------------------+------------------------------------+ +| 400-499 | the client request has a problem | ++---------------------------+------------------------------------+ +| 500-599 | the DMaaP service has a problem | ++---------------------------+------------------------------------+ + + +Sample Request: +=============== + ++-----------------------------------------------------------------------------------------------------------------------------------+ +| GET http://:3904/topic/com.att.dmaap.mr.testtopic | +| curl -u XXX@csp.abc.com:x$ -X | +| GET http://mrlocal00.dcae.proto.research.att.com:3904/topics | +| {"topics": [ | +| {"txenabled": true,"description": "This is a TestTopic","owner": "XXXX@csp.abc.com","topicName": "org.onap.dmaap.mr.Load9"| +| {"txenabled": false,"description": "", "owner": "", "topicName": "org.onap.dmaap.mr.Load1" | +| ]}, | ++-----------------------------------------------------------------------------------------------------------------------------------+ + + +Delete Topics +------------- + +Request URL: +============ + +DELETE http(s)://{HOST:PORT}/topic/{topicname} + +**NOTE**:To delete a topic, user must have the AAF permission +org.onap.dmaap.mr.topicFactory|:org.onap.dmaap.mr.topic:org.onap.dmaap.mr|destroy + +Sample Request: +=============== +ex: http://:3904/dmaap/v1/topics/org.onap.dmaap.mr.testopic + ++---------------------------+------------------------------------+ +| Response statusCode | Response statusMessage | ++===========================+====================================+ +| 200-299 | Success | ++---------------------------+------------------------------------+ +| 400-499 | the client request has a problem | ++---------------------------+------------------------------------+ +| 500-599 | the DMaaP service has a problem | ++---------------------------+------------------------------------+ + ++-------------------------+---------------------------------------------+----------------------+ +| Error code | Description |HTTP code | ++=========================+=============================================+======================+ +| DMaaP\_MR\_ERR\_5004 | Failed to delete topic: | 500 | ++-------------------------+---------------------------------------------+----------------------+ + +API Inventory +------------- + ++-----------+--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+ +| | API Name | API Method | REST API Path | | Comments | ++===========+====================+=========================================+=======================================+================+==================================+ +| Topics | GetAll Topics | getTopics() | /topics | GET | | +| | List | | | | | +| +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+ +| | Get All Topics | | | | | +| | List with details | getAllTopics() | /topics/listAll | GET | | +| +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+ +| | Get individual | | | | | +| | Topic Details | getTopic(String topicName) | /topics/{topicName} | GET | | +| +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+ +| | Create Topic | createTopic(TopicBean topicBean) | /topics/create | POST | | +| +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+ +| | Delete Topic | deleteTopicString topicName) | /topics/{topicName} | DELETE | Not used in current MR version | +| +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+ +| | Get Publishers | getPublishersByTopicName | | | | +| | for a Topic | String topicName) | /topics/{topicName}/producers | GET | UEB Backward Compatibility | +| +--------------------+-----------------------------------------+---------------------------------------+----------------+ | +| | Add a Publisher | permitPublisherForTopic | /topics/{topicName}/producers/ | PUT | | +| | to write ACLon | (String topicName, String producerId) | {producerId} | | | +| | a Topic | | | | | +| +--------------------+-----------------------------------------+---------------------------------------+----------------+ | +| | Remove a Publisher | denyPublisherForTopic(String topicName, | /topics/{topicName}/producers/ | DELETE | | +| | from write ACL on | String producerId) | {producerId} | | | +| | a Topic | | | | | +| +--------------------+-----------------------------------------+---------------------------------------+----------------+ | +| | Get Consumers for | getConsumersByTopicName | /topics/{topicName}/consumers | GET | | +| | a Topic | (String topicName) | | | | +| +--------------------+-----------------------------------------+---------------------------------------+----------------+ | +| | Add a Consumer | permitConsumerForTopic(String | /topics/{topicName}/consumers/ | PUT | | +| | to read ACL | topicName,String consumerId) | {consumerId} | | | +| | on a Topic | | | | | +| +--------------------+-----------------------------------------+---------------------------------------+----------------+ | +| | Remove a consumer | denyPublisherForTopic(String topicName, | /topics/{topicName}/consumers/ | DELETE | | +| | from write | String consumerId) | {consumerId} | | | +| | ACL on a Topic | | | | | ++-----------+--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+ + + + diff --git a/docs/offeredapis/offeredapis.rst b/docs/offeredapis/offeredapis.rst index 0428850..221cc06 100644 --- a/docs/offeredapis/offeredapis.rst +++ b/docs/offeredapis/offeredapis.rst @@ -1,535 +1,18 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 +.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. -Offered APIs -~~~~~~~~~~~~ - -.. toctree:: - :maxdepth: 3 - -DMaaP Message Router utilizes an HTTP REST API to service all Publish -and Consume transactions. HTTP and REST standards are followed so -clients as varied as CURL, Java applications and even Web Browsers will -work to interact with Message Router.Message Router uses AAF for user's -authentication and authorization. - -General HTTP Requirements -------------------------- - -A DMaaP Message Router transactions consists of 4 distinct segments, -HTTP URL, HTTP Header, HTTP Body (POST) and HTTP Response. The general -considerations for each segment are as follows and are required for each -of the specific transactions described in this section. - -HTTP URL -------- - -http[s]://serverBaseURL{/routing}{resourcePath} - -- The serverBaseURL points to DMaaP Message Router host/port that will service the request. - -- The resourcePath specifies the specific service, or Topic, that the client is attempting to reach - -HTTP Header ------------ - -Specifies HTTP Headers, such as Content-Type, that define the parameters -of the HTTP Transaction - -HTTP Body ---------- - -The HTTP Body contains the topic content when Publishing or Consuming. -The Body may contain topic messages in several formats (like below) but -it must be noted, that, except in very specific circumstances, messages -are not inspected for content. - - -+-------------------------+-----------------------------------------------------------------------------------------------------------------+ -| Content-Type | Description | -+=========================+=================================================================================================================+ -| text/plain | Each line in the POST body is treated as a separate message. No partition key is specified, and therefore no | -| | order is guaranteed. This format is mainly for test, as messages are highly likely to be re-ordered when | -| | delivered through the Kafka cluster. | -+-------------------------+-----------------------------------------------------------------------------------------------------------------+ -| application/json | The payload maybe a single JSON object or a JSON array of JSON objects. Each object is handled as an individual | -| | message..Note that use of this format may result in equivalent but altered JSON objects sent to consumers. | -| | That's because MR uses a standard JSON parser to read each object into memory before pushing the object to the | -| | Kafka system. At that point, the JSON object is re-written from the in-memory object. This can result in | -| | re-ordered fields or changes in whitespace. If you want to preserve JSON objects exactly, | -| | use application/cambria. Recommended to follow the JSON format. | -+-------------------------+-----------------------------------------------------------------------------------------------------------------+ - -Publishers ------------ - -**Description**:Publishes data to Kafka server on the topic mentioned in the URL. -Messages will be in the request body - -The MessageRouter service has no requirements on what publishers can put -onto a topic. The messages are opaque to the service and are treated as -raw bytes. In general, passing JSON messages is preferred, but this is -due to higher-level features and related systems, not the MessageRouter -broker itself. - -Request URL -=========== - -POST http(s)://{HOST:PORT}/events/{topicname} - -Request Parameters -================== - -+--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+ -| Name | Description | Param Type | Data type | Max Len | Required | Format | Valid/EXample values | -+====================+==============================+==================+============+===========+=============+================================+=============================+ -| Topicname | topic name to be posted | Path | String | 40 | Y | | org.onap.dmaap.mr.testtopic | -+--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+ -| content-type | To specify type of message | Header | String | 20 | N | | application/json | -+--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+ -| Username | userid | Header | String | | N | Basic Authentication Header | | -+--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+ -| Password | | Header | String | | N | Basic Authentication Header | | -+--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+ -| partitionKey | | QueryParam | String | | N | String value | ?Partitionkey=123 | -+--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+ - -**NOTE**: To publish data to the authenticated topic, Publisher must - have the AAF permission org.onap.dmaap.mr.topic|:topic.|pub. -Publishers may use DMaaP BusController for provisoning the AAF permissions - -Response Parameters -=================== - -+------------------+------------------------+------------+--------------+------------------------------+ -| Name | Description | Type | Format | Valid/Example Values | -+==================+========================+============+==============+==============================+ -| httpStatusCode | | | | 200, 201 etc. | -+------------------+------------------------+------------+--------------+------------------------------+ -| mrErrorCode | Numeric error code | | | 200, 201 etc. | -+------------------+------------------------+------------+--------------+------------------------------+ -| errorMessage | | | | SUCCESS, or error message. | -+------------------+------------------------+------------+--------------+------------------------------+ -| helpURL | helpurl | | | | -+------------------+------------------------+------------+--------------+------------------------------+ -| transactionid | transaction-id value | | | | -+------------------+------------------------+------------+--------------+------------------------------+ - - - -Response /Error Codes -===================== - -+---------------------------+------------------------------------+ -| Response statusCode | Response statusMessage | -+===========================+====================================+ -| 200-299 | Success | -+---------------------------+------------------------------------+ -| 400-499 | the client request has a problem | -+---------------------------+------------------------------------+ -| 500-599 | the DMaaP service has a problem | -+---------------------------+------------------------------------+ - -+------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+ -| Error code | HTTPCode | Description | Issue Reason | -+========================+===============+=================================+=========================================================================================================+ -| DMaaP\_MR\_ERR\_3001 | 413 | Request Entity too large | Message size exceeds the batch limit .Reduce the batch size and try again | -+------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+ -| DMaaP\_MR\_ERR\_3002 | 500 | Internal Server Error | Unable to publish messages. Please contact administrator | -+------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+ -| DMaaP\_MR\_ERR\_3003 | 400 | Bad Request | Incorrect Batching format. Please correct the batching format and try again | -+------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+ -| DMaaP\_MR\_ERR\_3004 | 413 | Request Entity too large | Message size exceeds the message size limit .Reduce the message size and try again | -+------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+ -| DMaaP\_MR\_ERR\_3005 | 400 | Bad Request | Incorrect JSON object. Please correct the JSON format and try again | -+------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+ -| DMaaP\_MR\_ERR\_3006 | 504 | Network Connect Timeout Error | Connection to the DMaaP MR was timed out.Please try again | -+------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+ -| DMaaP\_MR\_ERR\_3007 | 500 | Internal Server Error | Failed to publish messages to topic . Successfully published number of messages. | -+------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+ - -Sample Request: -=============== - -+-----------------------------------------------------------------------------------+ -| POST | -| | -| *Payload-* *{"message":"message description"}* *Content-Type: application/json* | -| | -| Example: | -| | -| curl -u XXXX@abc.com:X -H 'Content-Type:text/plain' -X POST -d @sampleMsg.txt | -| | -| { "count": 1, | -| | -| "serverTimeMs": 19" | -| | -| } | -+-----------------------------------------------------------------------------------+ - -Sample Response: -================ - -+---------------------------------------------------------------------+ -| HTTP/1.1 200 OK | -| | -| Server: Apache-Coyote/1.1 | -| | -| transactionId: 28-12-2015::08:18:50:682::::28122015552391 | -| | -| Content-Type: application/json | -| | -| Content-Length: 42 | -| | -| Date: Mon, 28 Dec 2015 13:18:50 GMT | -+---------------------------------------------------------------------+ - - - -Subscribers ------------ -**Description**:To subscribe to a MessageRouter topic, a subscriber issues a GET to the RESTful HTTP endpoint for events. - -Request URL: -============ - -GET http(s)://{HOST:PORT}}/events/{topicname}/{consumegroup}/{consumerid}/{timeout=x} - -Request Parameters: -=================== - -+--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+ -| Name | Description | Param Type | data type | MaxLen | Required | Format | Valid/Example Values | -+==============+=================================+==================+============+==============+=============+=====================+========================+ -| Topicname | topic name to be posted | Path | String | 40 | Y | | | -+--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+ -| Consumer | A name that uniquely identifies | Path | String | | Y | | CG1 | -| group | your subscribers | | | | | | | -+--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+ -| consumerId | Within your subscribers group, | Path | String | | Y | | C1 | -| | a name that uniquely identifies | | | | | | | -| | your subscribers process | | | | | | | -+--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+ -| content-type | To specify type of message | Header | String | 20 | N | | aplication/json | -| | content(json,text or cambria) | | | | | | | -+--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+ -| Username | userid | Header | String | 1 | N | | | -+--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+ -| Password | | Header | String | 1 | N | | | -+--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+ - -**NOTE**:To read data from a authenticated topic, User must have the -AAF permission org.onap.dmaap.mr.topic|:topic.|sub. -Subscribers may use DMaaP BusController for provisoning the permissions in AAF - -Response Parameters: -==================== - -+------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ -| Name | Description | Type | Format | Valid/Example Values | -+==================+================================+============+==============+===========================================================+ -| httpStatusCode | | | | 200, 201 etc. | -+------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ -| mrErrorCode | Numeric error code | | | 200, 201 etc. | -+------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ -| errorMessage | | | | SUCCESS, or error message. | -+------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ -| helpURL | helpurl | | | | -+------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ -| tranactionid | transaction-id value | | | 28-12-2015::08:18:50:682::135.25.227.66::28122015552391 | -+------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ -| ResponseBody | Messages consumed from topic | Json | Json | | -+------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ - - -Response /Error Codes -===================== -+---------------------------+------------------------------------+ -| Response statusCode | Response statusMessage | -+===========================+====================================+ -| 200-299 | Success | -+---------------------------+------------------------------------+ -| 400-499 | the client request has a problem | -+---------------------------+------------------------------------+ -| 500-599 | the DMaaP service has a problem | -+---------------------------+------------------------------------+ - -+-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+ -| Error code | HTTPCode | Description | Issue Reason | -+=========================+=================+============================+=============================================================================================+ -| DMaaP\_MR\_ERR\_3008 | 413 | Request Entity too large | Message size exceeds the batch limit .Reduce the batch size and try again | -+-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+ -| DMaaP\_MR\_ERR\_3009 | 500 | Internal Server Error | Unable to publish messages. Please contact administrator | -+-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+ -| DMaaP\_MR\_ERR\_3010 | 400 | Bad Request | Incorrect Batching format. Please correct the batching format and try again | -+-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+ -| DMaaP\_MR\_ERR\_3011 | 413 | Request Entity too large | Message size exceeds the message size limit .Reduce the message size and try again | -+-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+ -| DMaaP\_MR\_ERR\_5012 | 429 | Too many requests | This client is making too many requests. Please use a long poll setting to decrease the | -| | | | number of requests that result in empty responses. | -+-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+ -| | 503 | Service Unavailable | Service Unavailable. | -+-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+ - -Sample Request: -=============== - -+----------------------------------------------------------------------------------------------------+ -| GET http://:3904/events/com.att.dmaap.mr.sprint/mygroup/mycus | -| | -| Content-Type: application/json | -| | -| Example: | -| | -|curl -u XXX@csp.abc.com:MRDmap2016$ -X GET -d 'MyfirstMessage' | -| | -|http://mrlocal00.dcae.proto.research.att.com:3904/events/com.att.ecomp_test.crm.preDeo/myG/C1 | -| | -|[I am r sending first msg,I am R sending first msg] | -+----------------------------------------------------------------------------------------------------+ - -Provisioning ------------- -**Description**: To create , modify or delete the MessageRouter topics.These APIs can also be used by other applications to provision topics in MessageRouter. -DMaaP BusController is recommended for topic and AAf permissions provisoning - -Create Topic -============ -Request URL: -============ - -POST http(s)://{HOST:PORT}/topics/create - -Request Parameters: -=================== - -+-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+ -| Name | Description | Param Type | datatype | MaxLen | Required | Format | Valid/Example Values | -+===================+=================================+==================+============+==============+=============+=============+===================================+ -| Topicname | topicname to be created in MR | Body | String | 20 | Y | Json | org.onap.dmaap.mr.metrics | -+-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+ -| topicDescription | description for topic | Body | String | 15 | Y | | | -+-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+ -| partitionCount | Kafka topic partition | Body | String | 1 | Y | | | -+-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+ -| replicationCount | Kafka topic replication | Body | String | 1 | Y | | 3 (Default -for 3 node Kafka ) | -+-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+ -| transaction | to create transaction id for | Body | Boolean | 1 | N | | true | -| Enabled | each message transaction | | | | | | | -+-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+ -| Content-Type | application/json | Header | String | | | | application/json | -+-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+ - -**NOTE**:To Create a authenticated topic, user must have the AAF permission - org.onap.dmaap.mr.topicFactory|:org.onap.dmaap.mr.topic:org.onap.dmaap.mr|create - - -+---------------------------+------------------------------------+ -| Response statusCode | Response statusMessage | -+===========================+====================================+ -| 200-299 | Success | -+---------------------------+------------------------------------+ -| 400-499 | the client request has a problem | -+---------------------------+------------------------------------+ -| 500-599 | the DMaaP service has a problem | -+---------------------------+------------------------------------+ - - -+-------------------------+-----------------+--------------------------------------------------+ -| Error code | HTTP Code | Description | -+=========================+=================+==================================================+ -| DMaaP\_MR\_ERR\_5001 | 500 | Failed to retrieve list of all topics | -+-------------------------+-----------------+--------------------------------------------------+ -| DMaaP\_MR\_ERR\_5002 | 500 | Failed to retrieve details of topic: | -+-------------------------+-----------------+--------------------------------------------------+ -| DMaaP\_MR\_ERR\_5003 | 500 | Failed to create topic: | -+-------------------------+-----------------+--------------------------------------------------+ -| DMaaP\_MR\_ERR\_5004 | 500 | Failed to delete topic: | -+-------------------------+-----------------+--------------------------------------------------+ - - -Response Parameters -==================== - -+------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ -| Name | Description | Type | Format | Valid/Example Values | -+==================+================================+============+==============+===========================================================+ -| httpStatusCode | | | | 200, 201 etc. | -+------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ -| mrErrorCode | Numeric error code | | | 5005 | -+------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ -| errorMessage | | | | SUCCESS, or error message. | -+------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ -| helpURL | helpurl | | | | -+------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ -| ResponseBody | Topic details (owner, | Json | Json | | -| | trxEnabled=true) | | | | -+------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+ - - -Sample Request: -=============== - - .. code:: bash - - POST http://:3904/topic/create - Request Body - {"topicName":"org.onap.dmaap.mr.testtopic","description":"This is a test Topic ", - "partitionCount":"1","replicationCount":"3","transactionEnabled":"true"} - Content-Type: application/json - Example: - curl -u XXXc@csp.abc.com:xxxxx$ -H 'Content-Type:application/json' -X POST -d - @topicname.txt http://message-router:3904/topics/create - { - "writerAcl": { - "enabled": false, - "users": [] - }, - "description": "This is a TestTopic", - "name": "org.onap.dmaap.mr.testtopic", - "readerAcl": { - "enabled": false, - "users": [] - - -GetTopic Details ----------------- - -Request URL -=========== - -GET http(s)://{HOST:PORT}/topics : To list the details of all the topics in Message Router. - -GET http(s)://{HOST:PORT}/topics/{topicname} : To list the details of specified topic . - -Request Parameters -================== - -+--------------------------+-------------------------+------------------+------------+-----------+-------------+-----------------+-----------------------------+ -| Name | Description | Param Type | Data type | Max Len | Required | Format | Valid/EXample values | -+==========================+=========================+==================+============+===========+=============+=================+=============================+ -| Topicname | topic name details | Body | String | 20 | Y | Json | org.onap.dmaap.mr.testtopic | -+--------------------------+-------------------------+------------------+------------+-----------+-------------+-----------------+-----------------------------+ - -**NOTE**:To view a authenticated topic, user must have the AAF permission - org.onap.dmaap.mr.topic|*|view - - -Response Parameters -==================== - -+------------------+------------------------+------------+----------+---------+----------------------------+ -| Name | Description | ParamType | datatype |Format | Valid/Example Values | -+==================+========================+============+==========+=========+============================+ -| topicname | topic name details | Body | String | Json | org.onap.dmaap.mr.testopic | -+------------------+------------------------+------------+----------+---------+----------------------------+ -| description | | | String | | | -+------------------+------------------------+------------+----------+---------+----------------------------+ -| owner |user id who created the | | | | | -| | topic | | | | | -+------------------+------------------------+------------+----------+---------+----------------------------+ -| txenabled | true or false | | boolean | | | -+------------------+------------------------+------------+----------+---------+----------------------------+ - -+---------------------------+------------------------------------+ -| Response statusCode | Response statusMessage | -+===========================+====================================+ -| 200-299 | Success | -+---------------------------+------------------------------------+ -| 400-499 | the client request has a problem | -+---------------------------+------------------------------------+ -| 500-599 | the DMaaP service has a problem | -+---------------------------+------------------------------------+ - - -Sample Request: -=============== - -+-----------------------------------------------------------------------------------------------------------------------------------+ -| GET http://:3904/topic/com.att.dmaap.mr.testtopic | -| curl -u XXX@csp.abc.com:x$ -X | -| GET http://mrlocal00.dcae.proto.research.att.com:3904/topics | -| {"topics": [ | -| {"txenabled": true,"description": "This is a TestTopic","owner": "XXXX@csp.abc.com","topicName": "org.onap.dmaap.mr.Load9"| -| {"txenabled": false,"description": "", "owner": "", "topicName": "org.onap.dmaap.mr.Load1" | -| ]}, | -+-----------------------------------------------------------------------------------------------------------------------------------+ - - -Delete Topics -------------- - -Request URL: +Offered APIs ============ +.. toctree:: + :maxdepth: 1 -DELETE http(s)://{HOST:PORT}/topic/{topicname} - -**NOTE**:To delete a topic, user must have the AAF permission -org.onap.dmaap.mr.topicFactory|:org.onap.dmaap.mr.topic:org.onap.dmaap.mr|destroy - -Sample Request: -=============== -ex: http://:3904/dmaap/v1/topics/org.onap.dmaap.mr.testopic - -+---------------------------+------------------------------------+ -| Response statusCode | Response statusMessage | -+===========================+====================================+ -| 200-299 | Success | -+---------------------------+------------------------------------+ -| 400-499 | the client request has a problem | -+---------------------------+------------------------------------+ -| 500-599 | the DMaaP service has a problem | -+---------------------------+------------------------------------+ - -+-------------------------+---------------------------------------------+----------------------+ -| Error code | Description |HTTP code | -+=========================+=============================================+======================+ -| DMaaP\_MR\_ERR\_5004 | Failed to delete topic: | 500 | -+-------------------------+---------------------------------------------+----------------------+ - -API Inventory -------------- + offeredapis/swaggerdownload.rst + offeredapis/swaggerapi.rst + offeredapis/api.rst -+-----------+--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+ -| | API Name | API Method | REST API Path | | Comments | -+===========+====================+=========================================+=======================================+================+==================================+ -| Topics | GetAll Topics | getTopics() | /topics | GET | | -| | List | | | | | -| +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+ -| | Get All Topics | | | | | -| | List with details | getAllTopics() | /topics/listAll | GET | | -| +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+ -| | Get individual | | | | | -| | Topic Details | getTopic(String topicName) | /topics/{topicName} | GET | | -| +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+ -| | Create Topic | createTopic(TopicBean topicBean) | /topics/create | POST | | -| +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+ -| | Delete Topic | deleteTopicString topicName) | /topics/{topicName} | DELETE | Not used in current MR version | -| +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+ -| | Get Publishers | getPublishersByTopicName | | | | -| | for a Topic | String topicName) | /topics/{topicName}/producers | GET | UEB Backward Compatibility | -| +--------------------+-----------------------------------------+---------------------------------------+----------------+ | -| | Add a Publisher | permitPublisherForTopic | /topics/{topicName}/producers/ | PUT | | -| | to write ACLon | (String topicName, String producerId) | {producerId} | | | -| | a Topic | | | | | -| +--------------------+-----------------------------------------+---------------------------------------+----------------+ | -| | Remove a Publisher | denyPublisherForTopic(String topicName, | /topics/{topicName}/producers/ | DELETE | | -| | from write ACL on | String producerId) | {producerId} | | | -| | a Topic | | | | | -| +--------------------+-----------------------------------------+---------------------------------------+----------------+ | -| | Get Consumers for | getConsumersByTopicName | /topics/{topicName}/consumers | GET | | -| | a Topic | (String topicName) | | | | -| +--------------------+-----------------------------------------+---------------------------------------+----------------+ | -| | Add a Consumer | permitConsumerForTopic(String | /topics/{topicName}/consumers/ | PUT | | -| | to read ACL | topicName,String consumerId) | {consumerId} | | | -| | on a Topic | | | | | -| +--------------------+-----------------------------------------+---------------------------------------+----------------+ | -| | Remove a consumer | denyPublisherForTopic(String topicName, | /topics/{topicName}/consumers/ | DELETE | | -| | from write | String consumerId) | {consumerId} | | | -| | ACL on a Topic | | | | | -+-----------+--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+ diff --git a/docs/offeredapis/swagger .json b/docs/offeredapis/swagger .json new file mode 100644 index 0000000..44a2716 --- /dev/null +++ b/docs/offeredapis/swagger .json @@ -0,0 +1,863 @@ +{ + "swagger": "2.0", + "info": { + "description": "DMaaP MR REST API", + "version": "4.0.0", + "title": "DMaaP MR REST API" + }, + "host": "message-router:30227", + "basePath": "/", + "tags": [ + { + "name": "Topic", + "description": "Operations about topic" + }, + { + "name": "MirrorMaker", + "description": "Operations about mirror maker" + }, + { + "name": "MirrorMaker Whitelist", + "description": "Operations about mirror maker whitelist" + } + ], + "schemes": [ + "http", + "https" + ], + "paths": { + "/topics/create": { + "post": { + "tags": [ + "Topic" + ], + "summary": "Create a Topic", + "description": "AAF Permissions required to create authenticated topics: org.onap.dmaap.mr.topicFactory|:org.onap.dmaap.mr.topic:org.onap.dmaap.mr|create ", + "operationId": "Create a Topic", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "Topic details", + "required": true, + "schema": { + "$ref": "#/definitions/createTopic" + } + } + ], + "responses": { + "200": { + "description": "successful operation" + }, + "401": { + "description": "unauthorized" + }, + "403": { + "description": "forbidden" + }, + "409": { + "description": "topic already exist" + }, + "500": { + "description": "failed to create a topic" + } + }, + "security": [ + { + "basicAuth": [] + } + ] + } + }, + "/topics": { + "get": { + "tags": [ + "Topic" + ], + "summary": "Get all topics", + "description": "", + "operationId": "view all topics", + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "successful operation" + }, + "500": { + "description": "failed to return the topics" + } + } + } + }, + "/topics/{topicName}": { + "get": { + "tags": [ + "Topic" + ], + "summary": "Get individual topic details", + "description": "", + "operationId": "view the topic", + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "topicName", + "in": "path", + "description": "topicName", + "required": true, + "type": "string" + } + ], + "responses": { + "200": { + "description": "successful operation" + }, + "404": { + "description": "topic not found" + }, + "500": { + "description": "failed to return the topics" + } + } + } + }, + "/topics/listAll": { + "get": { + "tags": [ + "Topic" + ], + "summary": "Get all topics list with details", + "description": "", + "operationId": "view all topics details", + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "successful operation" + }, + "500": { + "description": "failed to return the topics" + } + } + } + }, + "/events/{topic}/{consumergroup}/{consumerid}": { + "get": { + "tags": [ + "Topic" + ], + "summary": "Get events from a topic", + "description": "Subscribe to a topic. If already subscribed read the events from the topic. Basic Auth header is required for subcribing to a topic. AAF permissions required for subscribing to a authenticated topic: org.onap.dmaap.mr.topic|:topic.|sub", + "operationId": "subscribe to a topic", + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "topic", + "in": "path", + "description": "topic name", + "required": true, + "type": "string" + }, + { + "name": "consumergroup", + "in": "path", + "description": "consumer group", + "required": true, + "type": "string" + }, + { + "name": "consumerid", + "in": "path", + "description": "consumer id", + "required": true, + "type": "string" + }, + { + "name": "limit", + "in": "query", + "description": "limit on the number of messages returned", + "type": "string" + }, + { + "name": "timeout", + "in": "query", + "description": "amount of time in ms server will open the connection with the Kafka while reading the messages", + "type": "string" + } + ], + "responses": { + "200": { + "description": "successful operation" + }, + "401": { + "description": "unauthorized" + }, + "403": { + "description": "forbidden" + }, + "409": { + "description": "unable to read the messages from the topic" + }, + "429": { + "description": "Client is making too many requests. Decrease the number of requests to avoid empty response" + }, + "500": { + "description": "internal server error" + } + }, + "security": [ + { + "basicAuth": [] + } + ] + } + }, + "/events/{topic}/": { + "post": { + "tags": [ + "Topic" + ], + "summary": "Post events to a topic", + "description": "post an event to a topic. Basic Auth header is required for subcribing to a topic. AAF permissions required for subscribing to a authenticated topic: org.onap.dmaap.mr.topic|:topic.|pub", + "operationId": "post messages to a topic", + "consumes": [ + "application/json", + "text/plain" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "topic", + "in": "path", + "description": "topic name", + "required": true, + "type": "string" + }, + { + "name": "partitionKey", + "in": "query", + "description": "topic partitionkey", + "type": "string" + }, + { + "in": "body", + "name": "body", + "description": "mesage/s to publish to a topic", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "successful operation" + }, + "400": { + "description": "Invalid request" + }, + "401": { + "description": "unauthorized" + }, + "403": { + "description": "forbidden" + }, + "404": { + "description": "error while publishing to the topic" + }, + "500": { + "description": "internal server error" + } + }, + "security": [ + { + "basicAuth": [] + } + ] + } + }, + "/mirrormakers/create": { + "post": { + "tags": [ + "MirrorMaker" + ], + "summary": "Create a Mirror Maker process and returns the all mirror maker processes", + "description": "AAF Permissions required: org.onap.dmaap.mr.mirrormaker|*|admin", + "operationId": "Create a Mirror Maker process", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "Create Mirror Maker", + "required": true, + "schema": { + "$ref": "#/definitions/createMirrorMaker" + } + } + ], + "responses": { + "200": { + "description": "successful operation" + }, + "400": { + "description": "invalid request" + }, + "401": { + "description": "unauthorized" + }, + "403": { + "description": "forbidden" + }, + "503": { + "description": "list mirror maker not available" + } + }, + "security": [ + { + "basicAuth": [] + } + ] + } + }, + "/mirrormakers/update": { + "post": { + "tags": [ + "MirrorMaker" + ], + "summary": "Update a Mirror Maker process and returns the all mirror maker processes", + "description": "AAF Permissions required: org.onap.dmaap.mr.mirrormaker|*|admin", + "operationId": "Update a Mirror Maker process", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "Update Mirror Maker", + "required": true, + "schema": { + "$ref": "#/definitions/updateMirrorMaker" + } + } + ], + "responses": { + "200": { + "description": "successful operation" + }, + "400": { + "description": "invalid request" + }, + "401": { + "description": "unauthorized" + }, + "403": { + "description": "forbidden" + }, + "503": { + "description": "list mirror maker not available" + } + }, + "security": [ + { + "basicAuth": [] + } + ] + } + }, + "/mirrormakers/listAll": { + "post": { + "tags": [ + "MirrorMaker" + ], + "summary": "List of mirror maker processes", + "description": "AAF Permissions required: org.onap.dmaap.mr.mirrormaker|*|admin", + "operationId": "List all Mirror Maker processes", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "List all Mirror Maker processes", + "required": true, + "schema": { + "$ref": "#/definitions/listAllMirrorMaker" + } + } + ], + "responses": { + "200": { + "description": "successful operation" + }, + "400": { + "description": "invalid request" + }, + "401": { + "description": "unauthorized" + }, + "403": { + "description": "forbidden" + }, + "503": { + "description": "list mirror maker not available" + } + }, + "security": [ + { + "basicAuth": [] + } + ] + } + }, + "/mirrormakers/delete": { + "post": { + "tags": [ + "MirrorMaker" + ], + "summary": "Delete a mirror maker process and return the all mirror maker processes", + "description": "AAF Permissions required: org.onap.dmaap.mr.mirrormaker|*|admin", + "operationId": "Delete a Mirror Maker process", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "Delete a Mirror Maker process", + "required": true, + "schema": { + "$ref": "#/definitions/deleteMirrorMaker" + } + } + ], + "responses": { + "200": { + "description": "successful operation" + }, + "400": { + "description": "invalid request" + }, + "401": { + "description": "unauthorized" + }, + "403": { + "description": "forbidden" + }, + "503": { + "description": "list mirror maker not available" + } + }, + "security": [ + { + "basicAuth": [] + } + ] + } + }, + "/mirrormakers/createwhitelist": { + "post": { + "tags": [ + "MirrorMaker Whitelist" + ], + "summary": "Add a new topic to a mirror maker whitelist and return all the mirror maker processes", + "description": "AAF Permissions required: rg.onap.dmaap.mr.mirrormaker|*|user , org.onap.dmaap.mr.topicFactory|:org.onap.dmaap.mr.topic:org.onap.dmaap.mr|create", + "operationId": "Create a whitelist", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "Add a topic to whitelist", + "required": true, + "schema": { + "$ref": "#/definitions/createWhitelist" + } + } + ], + "responses": { + "200": { + "description": "successful operation" + }, + "400": { + "description": "invalid request" + }, + "401": { + "description": "unauthorized" + }, + "403": { + "description": "forbidden" + }, + "503": { + "description": "list mirror maker not available" + } + }, + "security": [ + { + "basicAuth": [] + } + ] + } + }, + "/mirrormakers/listallwhitelist": { + "post": { + "tags": [ + "MirrorMaker Whitelist" + ], + "summary": "List all whitelist", + "description": "AAF Permissions required: rg.onap.dmaap.mr.mirrormaker|*|user , org.onap.dmaap.mr.topicFactory|:org.onap.dmaap.mr.topic:org.onap.dmaap.mr|create", + "operationId": "List all whitelist", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "List all whitelist", + "required": true, + "schema": { + "$ref": "#/definitions/listallwhitelist" + } + } + ], + "responses": { + "200": { + "description": "successful operation" + }, + "400": { + "description": "invalid request" + }, + "401": { + "description": "unauthorized" + }, + "403": { + "description": "forbidden" + }, + "503": { + "description": "list mirror maker not available" + } + }, + "security": [ + { + "basicAuth": [] + } + ] + } + }, + "/mirrormakers/deletewhitelist": { + "post": { + "tags": [ + "MirrorMaker Whitelist" + ], + "summary": "Delate a whitelist and returns the all lirror maker processes ", + "description": "AAF Permissions required: rg.onap.dmaap.mr.mirrormaker|*|user , org.onap.dmaap.mr.topicFactory|:org.onap.dmaap.mr.topic:org.onap.dmaap.mr|create", + "operationId": "Delete all whitelist", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "in": "body", + "name": "body", + "description": "List all whitelist", + "required": true, + "schema": { + "$ref": "#/definitions/listallwhitelist" + } + } + ], + "responses": { + "200": { + "description": "successful operation" + }, + "400": { + "description": "invalid request" + }, + "401": { + "description": "unauthorized" + }, + "403": { + "description": "forbidden" + }, + "503": { + "description": "list mirror maker not available" + } + }, + "security": [ + { + "basicAuth": [] + } + ] + } + } + }, + "securityDefinitions": { + "basicAuth": { + "type": "basic" + } + }, + "definitions": { + "createTopic": { + "type": "object", + "properties": { + "topicName": { + "type": "string", + "example": "org.onap.dmaap.mr.mrtesttopic" + }, + "topicDescription": { + "type": "string", + "example": "test topic" + }, + "partitionCount": { + "type": "integer", + "format": "int64", + "example": 3 + }, + "replicationCount": { + "type": "integer", + "format": "int64", + "example": 1 + }, + "transactionEnabled": { + "type": "string", + "example": "false" + } + } + }, + "createMirrorMaker": { + "type": "object", + "properties": { + "createMirrorMaker": { + "$ref": "#/definitions/createMirrorMaker.mirrorMaker" + } + } + }, + "createMirrorMaker.mirrorMaker": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Unique Name for the MirrorMaker. A-Z 1-0 only", + "example": "centraltoedge" + }, + "consumer": { + "type": "string", + "description": "Consumer hostname/IP Address", + "example": "10.12.6.98:30491" + }, + "producer": { + "type": "string", + "description": "Producer hostname/IP Address", + "example": "10.12.5.108:30491" + }, + "numStreams": { + "type": "string", + "description": "Number of consumer threads to start. (If not provided default is 1)", + "example": "3" + }, + "whitelist": { + "type": "string", + "description": "Topic names to be whitelisted. This can be provided later using createWhitelist API", + "example": "org.onap.dmaap.mr.mrtesttopic" + }, + "enablelogCheck": { + "type": "string", + "description": "Enable error log monitoring on the MirrorMaker thread. Default values is False.If not provided error log is not monitored.", + "example": "true" + } + }, + "required": [ + "name", + "consumer", + "producer" + ] + }, + "updateMirrorMaker": { + "type": "object", + "properties": { + "updateMirrorMaker": { + "$ref": "#/definitions/updateMirrorMaker.mirrorMaker" + } + } + }, + "updateMirrorMaker.mirrorMaker": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Existing Mirror Maker name", + "example": "centraltoedge" + }, + "consumer": { + "type": "string", + "description": "Consumer hostname/IP Address", + "example": "10.12.6.98:30491" + }, + "producer": { + "type": "string", + "description": "Producer hostname/IP Address", + "example": "10.12.5.108:30491" + }, + "numStreams": { + "type": "string", + "description": "Update number of consumer threads", + "example": "3" + }, + "enablelogCheck": { + "type": "string", + "description": "Enable/Disable error log monitoring on the MirrorMaker thread", + "example": "false" + } + }, + "required": [ + "name" + ] + }, + "listAllMirrorMaker": { + "type": "object", + "properties": { + "listAllMirrorMaker": { + "type": "object", + "items": { + "$ref": "#/definitions/listAllMirrorMaker.mirrorMaker" + } + } + } + }, + "listAllMirrorMaker.mirrorMaker": { + "type": "object" + }, + "deleteMirrorMaker": { + "type": "object", + "properties": { + "deleteMirrorMaker": { + "$ref": "#/definitions/deleteMirrorMaker.mirrorMaker" + } + } + }, + "deleteMirrorMaker.mirrorMaker": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Existing Mirror Maker name", + "example": "centraltoedge2" + } + }, + "required": [ + "name" + ] + }, + "createWhitelist": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Existing Mirror Maker name", + "example": "centraltoedge" + }, + "namespace": { + "type": "string", + "description": "", + "example": "org.onap.dmaap.mr" + }, + "whitelistTopicName": { + "type": "string", + "description": "Topic name to add to the whitelist", + "example": "org.onap.dmaap.mr.mrtesttopic2" + } + }, + "required": [ + "name", + "namespace", + "whitelistTopicName" + ] + }, + "listallwhitelist": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Existing Mirror Maker name", + "example": "centraltoedge" + }, + "namespace": { + "type": "string", + "description": "", + "example": "org.onap.dmaap.mr" + } + }, + "required": [ + "name", + "namespace" + ] + }, + "deleteeWhitelist": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Existing Mirror Maker name", + "example": "centraltoedge" + }, + "namespace": { + "type": "string", + "description": "", + "example": "org.onap.dmaap.mr" + }, + "whitelistTopicName": { + "type": "string", + "description": "Topic name to delete from the whitelist", + "example": "org.onap.dmaap.mr.mrtesttopic2" + } + }, + "required": [ + "name", + "namespace", + "whitelistTopicName" + ] + } + } +} \ No newline at end of file diff --git a/docs/offeredapis/swaggerapi.rst b/docs/offeredapis/swaggerapi.rst new file mode 100644 index 0000000..170ebbb --- /dev/null +++ b/docs/offeredapis/swaggerapi.rst @@ -0,0 +1,5 @@ +DMaaP Message Router API 4.0.0 (via swagger2doc) +===================================================== + + +.. swaggerv2doc:: swagger.json diff --git a/docs/offeredapis/swaggerdownload.rst b/docs/offeredapis/swaggerdownload.rst new file mode 100644 index 0000000..709aac3 --- /dev/null +++ b/docs/offeredapis/swaggerdownload.rst @@ -0,0 +1,13 @@ +DMaaP Message Router REST API Download docs +=========================================== + +.. toctree:: + :maxdepth: 3 + +.. this table is provided to allow for download of API documentation in diff formats + +.. csv-table:: + :header: "API name", "Swagger JSON" + :widths: 15,5 + + "DMaaP MessageRouter API", ":download:`link `"