Message Router (MR) API Guide\r
============================================\r
\r
-HTTP Service APIs:\r
-==================\r
+HTTP Service APIs\r
+------------------\r
\r
DMaaP Message Router utilizes an HTTP REST API to service all Publish\r
and Consume transactions. HTTP and REST standards are followed so\r
\r
http[s]://Username:Password@serverBaseURL{/routing}{resourcePath}\r
\r
-\95 The Username:Password utilizes HTTP Basic Authentication and HTTPS/TLS\r
+- The Username:Password utilizes HTTP Basic Authentication and HTTPS/TLS\r
to securely transmit the authorization and authentication credentials\r
that AAF needs to validate the client's access to the requested\r
resource.\r
-\r
-\95 The serverBaseURL points to DMaaP Message Router host/port that will\r
+- The serverBaseURL points to DMaaP Message Router host/port that will\r
service the request. Optionally DME2 service end points for Message\r
Router can be used.\r
-\r
-\95 The resourcePath specifies the specific service, or Topic, that the\r
+- The resourcePath specifies the specific service, or Topic, that the\r
client is attempting to reach\r
\r
HTTP Header\r
| | message in https://jsonformatter.curiousconcept.com/ |\r
+-------------------------+----------------------------------------------------------------------------------------------------------------+\r
\r
-\r
-\r
-\r
-DME2 Service endpoints:\r
-=======================\r
-\r
-Message Router supports DME2 clients. That is , Client application may\r
-use DME2Client and DME2 service address to call the MessageRouter\r
-service.\r
-\r
-Example DME2 service address:\r
-\r
-Please use DMaap Message Router Run Book for complete details\r
-\r
-TEST: http://hostname/events?version=XXX&envContext=XXX&partner=XX\r
-\r
-PROD: https://hostname/events?version=XXX &envContext=XXX&partner=XX\r
-\r
-The values of version/envContext/routerOffer may change based upon the\r
-environment.\r
-\r
-The specific details for each API are described as below\r
-\r
-\r
-\r
Publishers\r
-==========\r
-\r
-Description:\r
-===========\r
+-----------\r
\r
-Publishes data to Kafka server on the topic mentioned in the URL.\r
+**Description**:Publishes data to Kafka server on the topic mentioned in the URL.\r
Messages will be in the request body\r
\r
The MessageRouter service has no requirements on what publishers can put\r
size \96 messages must be under the maximum size, which is currently\r
configured at 1 MB.\r
\r
-Request URL:\r
+Request URL\r
===========\r
\r
POST http(s)://{HOST:PORT}/events/{topicname}\r
Request Parameters\r
==================\r
\r
-+--------------------------+---------------------------------+------------------+------------+-----------+-------------+--------------------------------+---------------------------------------------------+\r
-| Name | Description | Param Type | Data type | Max Len | Req\92d | Format | Valid/Example Values |\r
-+==========================+=================================+==================+============+===========+=============+================================+===================================================+\r
-| Topicname | topic name to be posted | Path | String | 40 | Y | <app namespace>.<topicname> | Org.onap.crm.empdetails |\r
-+--------------------------+---------------------------------+------------------+------------+-----------+-------------+--------------------------------+---------------------------------------------------+\r
-| `content-type | To specify type of message | Header | String | 20 | N | | application/json text/plain application/cambria |\r
-| | | | | | | | |\r
-| | content(json,text or cambria) | | | | | | |\r
-+--------------------------+---------------------------------+------------------+------------+-----------+-------------+--------------------------------+---------------------------------------------------+\r
-| Username | userid | Header | String | | N | Basic Authentication Header | |\r
-+--------------------------+---------------------------------+------------------+------------+-----------+-------------+--------------------------------+---------------------------------------------------+\r
-| Password | | Header | String | | N | Basic Authentication Header | |\r
-+--------------------------+---------------------------------+------------------+------------+-----------+-------------+--------------------------------+---------------------------------------------------+\r
-| partitionKey | | QueryParam | String | | N | String value | ?partitionKey=123 |\r
-+--------------------------+---------------------------------+------------------+------------+-----------+-------------+--------------------------------+---------------------------------------------------+\r
-\r
- \r
-\r
- \r
-\r
-Note:\r
------\r
-\r
-Publishers/user should have access on the topics. The user (id) and\r
++--------------------------+---------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+\r
+| Name | Description | Param Type | Data type | Max Len | Req\92d | Format | Valid/EXample values |\r
++==========================+=================================+==================+============+===========+=============+================================+=============================+\r
+| Topicname | topic name to be posted | Path | String | 40 | Y | <app namespace>.<topicname> | org.onap.crm.empdetails |\r
++--------------------------+---------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+\r
+| content-type | To specify type of message | Header | String | 20 | N | | application/json |\r
++--------------------------+---------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+| Username | userid | Header | String | | N | Basic Authentication Header | |\r
++--------------------------+---------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+\r
+| Password | userid | Header | String | | N | Basic Authentication Header | |\r
++--------------------------+---------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+\r
+| partitionKey | | QueryParam | String | | N | String value |?Partitionkey=123 |\r
++--------------------------+---------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+\r
+\r
+**NOTE:** Publishers/user should have access on the topics. The user (id) and\r
permissions details needs to be in AAF.\r
\r
-Response Parameters:\r
-====================\r
+Response Parameters\r
+===================\r
\r
+------------------+------------------------+------------+--------------+------------------------------+\r
| Name | Description | Type | Format | Valid/Example Values |\r
\r
\r
\r
-Response /Error Codes:\r
+Response /Error Codes\r
=====================\r
\r
+---------------------------+------------------------------------+\r
| 500-599 | the DMaaP service has a problem |\r
+---------------------------+------------------------------------+\r
\r
-+------------------------+----------------+---------------------------------+---------------------------------------------------------------------------------------------------------+\r
-| Error code | HTTPCode | Description | Issue Reason |\r
-+========================+================+=================================+=========================================================================================================+\r
-| DMaaP\_MR\_ERR\_3001 | 413 | Request Entity too large | Message size exceeds the batch limit <limit>.Reduce the batch size and try again |\r
-+------------------------+----------------+---------------------------------+---------------------------------------------------------------------------------------------------------+\r
-| DMaaP\_MR\_ERR\_3002 | 500 | Internal Server Error | Unable to publish messages. Please contact administrator |\r
-+------------------------+----------------+---------------------------------+---------------------------------------------------------------------------------------------------------+\r
-| DMaaP\_MR\_ERR\_3003 | 400 | Bad Request | Incorrect Batching format. Please correct the batching format and try again |\r
-+------------------------+----------------+---------------------------------+---------------------------------------------------------------------------------------------------------+\r
-| DMaaP\_MR\_ERR\_3004 | 413 | Request Entity too large | Message size exceeds the message size limit <limit>.Reduce the message size and try again |\r
-+------------------------+----------------+---------------------------------+---------------------------------------------------------------------------------------------------------+\r
-| DMaaP\_MR\_ERR\_3005 | 400 | Bad Request | Incorrect JSON object. Please correct the JSON format and try again |\r
-+------------------------+----------------+---------------------------------+---------------------------------------------------------------------------------------------------------+\r
-| DMaaP\_MR\_ERR\_3006 | 504 | Network Connect Timeout Error | Connection to the DMaaP MR was timed out.Please try again |\r
-+------------------------+----------------+---------------------------------+---------------------------------------------------------------------------------------------------------+\r
-| DMaaP\_MR\_ERR\_3007 | 500 | Internal Server Error | Failed to publish messages to topic <topicName>. Successfully published <count > number of messages. |\r
-+------------------------+----------------+---------------------------------+---------------------------------------------------------------------------------------------------------+\r
-| | 503 | Service Unavailable | Service Unavailable |\r
-+------------------------+----------------+---------------------------------+---------------------------------------------------------------------------------------------------------+\r
-\r
- \r
++------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+\r
+| Error code | HTTPCode | Description | Issue Reason |\r
++========================+===============+=================================+=========================================================================================================+\r
+| DMaaP\_MR\_ERR\_3001 | 413 | Request Entity too large | Message size exceeds the batch limit <limit>.Reduce the batch size and try again |\r
++------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+\r
+| DMaaP\_MR\_ERR\_3002 | 500 | Internal Server Error | Unable to publish messages. Please contact administrator |\r
++------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+\r
+| DMaaP\_MR\_ERR\_3003 | 400 | Bad Request | Incorrect Batching format. Please correct the batching format and try again |\r
++------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+\r
+| DMaaP\_MR\_ERR\_3004 | 413 | Request Entity too large | Message size exceeds the message size limit <limit>.Reduce the message size and try again |\r
++------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+\r
+| DMaaP\_MR\_ERR\_3005 | 400 | Bad Request | Incorrect JSON object. Please correct the JSON format and try again |\r
++------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+\r
+| DMaaP\_MR\_ERR\_3006 | 504 | Network Connect Timeout Error | Connection to the DMaaP MR was timed out.Please try again |\r
++------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+\r
+| DMaaP\_MR\_ERR\_3007 | 500 | Internal Server Error | Failed to publish messages to topic <topicName>. Successfully published <count > number of messages. |\r
++------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+\r
\r
Sample Request:\r
==============\r
\r
\r
\r
-Subscribers:\r
-===========\r
-\r
-Description:\r
-\r
- To subscribe to a MessageRouter topic, a subscriber issues a GET to the RESTful HTTP endpoint for events.\r
-\r
-\r
+Subscribers\r
+-----------\r
+**Description**:To subscribe to a MessageRouter topic, a subscriber issues a GET to the RESTful HTTP endpoint for events.\r
\r
Request URL:\r
============\r
+-------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-------------------------------------------------+\r
| content-type| To specify type of message | | | | | |aplication/json |\r
| | content(json,text or cambria) | Header | String | 20 | N | | |\r
-| | | | | | | | | \r
+-------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-------------------------------------------------+\r
|Username | userid | Header | String | 1 | N | | |\r
+-------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-------------------------------------------------+\r
| Password | | Header | String | 1 | N | | |\r
+-------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-------------------------------------------------+ \r
\r
-Note1: \r
-======\r
-Subscribers /user should have access on the topics. The user () and\r
+**NOTE1:**Subscribers /user should have access on the topics. The user () and\r
permissions details needs to be in AAF.\r
\r
-Note 2:\r
-=======\r
-\r
-\r
-A few consumer client app team who does continuous polling (by\r
-multiple rest calls) complained that they receive "503 consumer lock\r
-exception". The messages will not be lost from the topic when this\r
-exception occurs and it will be still in the topic. This happens when\r
-the concurrent rest call requests are made between several nodes in a\r
-cluster. Consumer lock is done at zookeeper level to ensure the offset\r
-for each consumer group is maintained to avoid losing the message in\r
-multiple concurrent calls of same consumer Group. We are looking\r
-otherways to resolve this issue. But for these continuous polling\r
-scenario, the suggested workaround is to ensure the request is made to\r
-only one node of the cluster. Session stickiness in DME2 is example of\r
-handling this. If this exception occurs , waiting for few minutes with\r
-out making api calls will release the lock in zookeeper.**\r
-\r
Response Parameters:\r
===================\r
\r
+------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+\r
| ResponseBody | Messages consumed from topic | Json | Json | |\r
+------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+\r
-\r
-\r
-\r
+|\r
+---------------------------+------------------------------------+\r
| Response statusCode | Response statusMessage |\r
+===========================+====================================+\r
+---------------------------+------------------------------------+\r
| 500-599 | the DMaaP service has a problem |\r
+---------------------------+------------------------------------+\r
-\r
-\r
-\r
+|\r
+-------------------------+-----------------+----------------------------+----------------------------------------------------------------------------------------------------+\r
| Error code | HTTP Code | Description |Issue reason |\r
+-------------------------+-----------------+----------------------------+----------------------------------------------------------------------------------------------------+\r
| DMaaP\_MR\_ERR\_3009 | 500 | Internal Server Error | Unable to publish messages. Please contact administartor | +-------------------------+-----------------+----------------------------+----------------------------------------------------------------------------------------------------+\r
| DMaaP\_MR\_ERR\_3010 | 400 | Bad Request | Incorrect Batching format. Please correct the batching format and try again | +-------------------------+-----------------+----------------------------+----------------------------------------------------------------------------------------------------+\r
| DMaaP\_MR\_ERR\_3011 | 413 | Request Entity too large | Message size exceeds the message size limit <limit>.Reduce the message size and try again | +-------------------------+-----------------+----------------------------+----------------------------------------------------------------------------------------------------+\r
-| 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. |\r
-+-------------------------+-----------------+----------------------------+----------------------------------------------------------------------------------------------------+\r
-| | 503 | Service Unavailable | Service Unavailable | +-------------------------+-----------------+----------------------------+----------------------------------------------------------------------------------------------------+\r
\r
\r
+Sample Request:\r
+==============\r
+\r
++----------------------------------------------------------------------------------------------------+\r
+| GET http://<hostname>:3904/events/com.att.dmaap.mr.sprint/mygroup/mycus |\r
+| Content-Type: application/json |\r
+| Example: |\r
+|curl -u XXX@csp.abc.com:MRDmap2016$ -X GET -d 'MyfirstMessage' | \r
+|http://mrlocal00.dcae.proto.research.att.com:3904/events/com.att.ecomp_test.crm.preDeo/myG/C1 |\r
+|[I am r sending first msg,I am R sending first msg] |\r
++----------------------------------------------------------------------------------------------------+\r
+\r
+Provisioning\r
+------------\r
+**Description**: To create , modify or delete the MessageRouter topics. Generally Invenio application will use these below apis to create , assign topics to the users. These APIs can also be used by other applications to provision topics in MessageRouter\r
+\r
+Create Topic\r
+============\r
+Request URL:\r
+============\r
+\r
+POST http(s)://{HOST:PORT}/topics/create\r
+\r
+Request Parameters:\r
+==================\r
+\r
++----------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+\r
+| Name | Description | Param Type | data type | MaxLen | Req\92d | Format | Valid/Example Values |\r
+| | | | | | | | |\r
++----------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+\r
+| Topicname | topicname to be created in MR | Body | String | 20 | Y | Json | com.att.dmaap.mr.metrics |\r
++----------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+ \r
+|topicDescription| description for topic | Body | String | 15 | Y | | |\r
++----------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+ \r
+|partitionCount | Kafka topic partition | Body | String | 1 | Y | | |\r
++----------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+ \r
+|replicationCount| Kafka topic replication | Body | String | 1 | Y | | 3 (Default -for 3 node Kafka ) |\r
++----------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+ \r
+|transaction |to create transaction id for | Body | Boolean | | | | |\r
+| | each message transaction | | | 1 | N | | true |\r
+| Enabled | | | | | | | | \r
++----------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+ \r
+|Content-Type | application/json | Header | String | | | | application/json |\r
++----------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+\r
+\r
++---------------------------+------------------------------------+\r
+| Response statusCode | Response statusMessage |\r
++===========================+====================================+\r
+| 200-299 | Success |\r
++---------------------------+------------------------------------+\r
+| 400-499 | the client request has a problem |\r
++---------------------------+------------------------------------+\r
+| 500-599 | the DMaaP service has a problem |\r
++---------------------------+------------------------------------+\r
+\r
++-------------------------+-----------------+--------------------------------------------------+\r
+| Error code | HTTP Code | Description |\r
++-------------------------+-----------------+--------------------------------------------------+\r
+| DMaaP\_MR\_ERR\_5001 | 500 | Failed to retrieve list of all topics | +-------------------------+-----------------+--------------------------------------------------+\r
+| DMaaP\_MR\_ERR\_5002 | 500 | Failed to retrieve details of topic:<topicName> | |+-------------------------+----------------+--------------------------------------------------+\r
+| DMaaP\_MR\_ERR\_5003 | 500 |Failed to create topic:<topicName> | +-------------------------+-----------------+--------------------------------------------------+\r
+| DMaaP\_MR\_ERR\_5004 | 500 | Failed to delete topic:<topicName> | +-------------------------+-----------------+--------------------------------------------------+\r
+\r
+Response Parameters\r
+====================\r
+\r
++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+\r
+| Name | Description | Type | Format | Valid/Example Values |\r
++==================+================================+============+==============+===========================================================+\r
+| httpStatusCode | | | | 200, 201 etc. |\r
++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+\r
+| mrErrorCode | Numeric error code | | |5005 |\r
++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+\r
+| errorMessage | | | | SUCCESS, or error message. |\r
++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+\r
+| helpURL | helpurl | | | |\r
++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+\r
+| ResponseBody | Topic details (owner, | | | |\r
+| | trxEnabled=true) | Json | Json | |\r
++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+\r
+\r
+\r
+Sample Request:\r
+==============\r
\r
++-----------------------------------------------------------------------------------+\r
+| POST http://<hostname>:3904/topic/create |\r
+|Request Body |\r
+|{"topicName":"com.att.dmaap.mr.topicname","description":"This is a SAPTopic ", |\r
+| "partitionCount":"1","replicationCount":"3","transactionEnabled":"true"} |\r
+| Content-Type: application/json |\r
+|Example: |\r
+|curl -u XXXc@csp.abc.com:xxxxx$ -H 'Content-Type:application/json' -X POST -d |\r
+|@topicname.txt http://mrlocal00.dcae.proto.research.att.com:3904/topics/create |\r
+|{ |\r
+| "writerAcl": { |\r
+| "enabled": false, |\r
+| "users": [] |\r
+| }, |\r
+| "description": "This is a TestTopic", |\r
+| "name": "com.att.ecomp_test.crm.Load9", |\r
+| "readerAcl": { |\r
+| "enabled": false, |\r
+| "users": [] |\r
++-----------------------------------------------------------------------------------+\r
+\r
+GetTopic Details\r
+----------------\r
+\r
+Request URL\r
+===========\r
+\r
+GET http(s)://{HOST:PORT}/topics : To list the details of all the topics in Message Router.\r
+\r
+GET http(s)://{HOST:PORT}/topics/{topicname} : To list the details of specified topic .\r
+\r
+Request Parameters\r
+==================\r
+\r
++--------------------------+---------------------------------+------------------+------------+-----------+-------------+-----------------+-----------------------------+\r
+| Name | Description | Param Type | Data type | Max Len | Req\92d | Format | Valid/EXample values |\r
++==========================+=================================+==================+============+===========+=============+=================+=============================+\r
+| Topicname | topic name details | Body | String | 20 | Y | Json | com.att.dmaap.mr.metrics |\r
++--------------------------+---------------------------------+------------------+------------+-----------+-------------+-----------------+-----------------------------+\r
+\r
+\r
+Response Parameters\r
+====================\r
+\r
++------------------+------------------------+------------+----------+---------+--------------------------+\r
+| Name | Description | ParamType | datatype |Format | Valid/Example Values |\r
++==================+========================+============+==========+=========+==========================+\r
+| topicname | topic name details | Body | String | Json | com.att.dmaap.mr.metrics | \r
++------------------+------------------------+------------+----------+---------+--------------------------+\r
+| description | | | String | | | \r
++------------------+------------------------+------------+----------+---------+--------------------------+\r
+|owner |user id who created the | | | | |\r
+| | topic | | | | | \r
++------------------+------------------------+------------+----------+---------+--------------------------+\r
+| txenabled | true or false | | boolean| | | \r
++------------------+------------------------+------------+----------+---------+--------------------------+\r
+\r
++---------------------------+------------------------------------+\r
+| Response statusCode | Response statusMessage |\r
++===========================+====================================+\r
+| 200-299 | Success |\r
++---------------------------+------------------------------------+\r
+| 400-499 | the client request has a problem |\r
++---------------------------+------------------------------------+\r
+| 500-599 | the DMaaP service has a problem |\r
++---------------------------+------------------------------------+\r
+\r
+\r
+Sample Request:\r
+==============\r
+\r
++-----------------------------------------------------------------------------------+\r
+| GET http://<hostname>:3904/topic/com.att.dmaap.mr.testtopic |\r
+| curl -u XXX@csp.abc.com:x$ -X |\r
+| GET http://mrlocal00.dcae.proto.research.att.com:3904/topics |\r
+| {"topics": [ |\r
+| { |\r
+| "txenabled": true, |\r
+| "description": "This is a TestTopic", |\r
+| "owner": "rs857c@csp.att.com", |\r
+| "topicName": "com.att.ecomp_test.crm.Load9" |\r
+| }, |\r
+| { |\r
+| "txenabled": false, |\r
+| "description": "", |\r
+| "owner": "", |\r
+| "topicName": "com.att.ecomp_test.crm.Load1" |\r
+| }, |\r
++-----------------------------------------------------------------------------------+\r
+\r
+\r
+Delete Topics\r
+-------------\r
+\r
+Request URL:\r
+===========\r
+\r
+DELETE http(s)://{HOST:PORT}/topic/{topicname}\r
+\r
+Sample Request:\r
+==============\r
+ex: http://<hostname>:3904/dmaap/v1/topics/com.att.dmaap.mr.testopic\r
+\r
++---------------------------+------------------------------------+\r
+| Response statusCode | Response statusMessage |\r
++===========================+====================================+\r
+| 200-299 | Success |\r
++---------------------------+------------------------------------+\r
+| 400-499 | the client request has a problem |\r
++---------------------------+------------------------------------+\r
+| 500-599 | the DMaaP service has a problem |\r
++---------------------------+------------------------------------+\r
\r
++-------------------------+---------------------------------------------+----------------------+\r
+| Error code | Description |HTTP code |\r
++-------------------------+---------------------------------------------+----------------------+\r
+| DMaaP\_MR\_ERR\_5004 | Failed to delete topic:<topicName> | 500 | \r
++-------------------------+---------------------------------------------+----------------------+\r
\r
Code Review / dmaap / messagerouter / messageservice.git / commitdiff