--- /dev/null
+============================================\r
+Message Router (MR) API Guide\r
+============================================\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
+clients as varied as CURL, Java applications and even Web Browsers will\r
+work to interact with Message Router.Message Router uses AAF for user's\r
+authentication and authorization.\r
+\r
+General HTTP Requirements\r
+=========================\r
+\r
+A DMaaP Message Router transactions consists of 4 distinct segments,\r
+HTTP URL, HTTP Header, HTTP Body (POST) and HTTP Response. The general\r
+considerations for each segment are as follows and are required for each\r
+of the specific transactions described in this section.\r
+\r
+HTTP URL\r
+========\r
+\r
+http[s]://Username:Password@serverBaseURL{/routing}{resourcePath}\r
+\r
+\95 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
+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
+client is attempting to reach\r
+\r
+HTTP Header\r
+===========\r
+\r
+Specifies HTTP Headers, such as Content-Type, that define the parameters\r
+of the HTTP Transaction\r
+\r
+HTTP Body\r
+=========\r
+\r
+The HTTP Body contains the topic content when Publishing or Consuming.\r
+The Body may contain topic messages in several formats (like below) but\r
+it must be noted, that, except in very specific circumstances, messages\r
+are not inspected for content.\r
+\r
+\r
++-------------------------+----------------------------------------------------------------------------------------------------------------+\r
+| Content-Type | Description |\r
++=========================+================================================================================================================+\r
+| text/plain | Each line in the POST body is treated as a separate message. No partition key is specified, and therefore no |\r
+| | order is guaranteed. This format is mainly for test, as messages are highly likely to be re-ordered when |\r
+| | delivered through the Kafka cluster. |\r
++-------------------------+----------------------------------------------------------------------------------------------------------------+\r
+| application/json | The payload maybe a single JSON object or a JSON array of JSON objects. Each object is handled as an individual|\r
+| | message..Note that use of this format may result in equivalent but altered JSON objects sent to consumers. | \r
+| | That's because MR uses a standard JSON parser to read each object into memory before pushing the object to the |\r
+| | Kafka system. At that point, the JSON object is re-written from the in-memory object. This can result in |\r
+| | re-ordered fields or changes in whitespace. If you want to preseve JSON objects exactly, |\r
+| | use application/cambria. Recommended to follow the JSON format after validating the |\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
+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
+onto a topic. The messages are opaque to the service and are treated as\r
+raw bytes. In general, passing JSON messages is preferred, but this is\r
+due to higher-level features and related systems, not the MessageRouter\r
+broker itself. The only constraint placed on messages is their on their\r
+size \96 messages must be under the maximum size, which is currently\r
+configured at 1 MB.\r
+\r
+Request URL:\r
+===========\r
+\r
+POST http(s)://{HOST:PORT}/events/{topicname}\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 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
+permissions details needs to be in AAF.\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 | | | 200, 201 etc. |\r
++------------------+------------------------+------------+--------------+------------------------------+\r
+| errorMessage | | | | SUCCESS, or error message. |\r
++------------------+------------------------+------------+--------------+------------------------------+\r
+| helpURL | helpurl | | | |\r
++------------------+------------------------+------------+--------------+------------------------------+\r
+| transactionid | transaction-id value | | | |\r
++------------------+------------------------+------------+--------------+------------------------------+\r
+\r
+ \r
+\r
+Response /Error Codes:\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 | 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
+Sample Request:\r
+==============\r
+\r
++-----------------------------------------------------------------------------------+\r
+| POST |\r
+| |\r
+| *Payload-* *{"message":"message description"}* *Content-Type: application/json* |\r
+| |\r
+| Example: |\r
+| |\r
+| curl -u XXXX@abc.com:X -H 'Content-Type:text/plain' -X POST -d @sampleMsg.txt |\r
+| |\r
+| { "count": 1, |\r
+| |\r
+| "serverTimeMs": 19" |\r
+| |\r
+| } |\r
++-----------------------------------------------------------------------------------+\r
+\r
+Sample Response:\r
+===============\r
+\r
++---------------------------------------------------------------------+\r
+| HTTP/1.1 200 OK |\r
+| |\r
+| Server: Apache-Coyote/1.1 |\r
+| |\r
+| transactionId: 28-12-2015::08:18:50:682::<IP>::28122015552391 |\r
+| |\r
+| Content-Type: application/json |\r
+| |\r
+| Content-Length: 42 |\r
+| |\r
+| Date: Mon, 28 Dec 2015 13:18:50 GMT |\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
+\r
+Request URL:\r
+============\r
+\r
+GET http(s)://{HOST:PORT}}/events/{topicname}/{consumegroup}/{consumerid}?{timeout=x}\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 | topic name to be posted | Path | String | 40 | Y | namespace. | |\r
+| | | | | | | String | |\r
++-------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-------------------------------------------------+ \r
+|Consumergroup| A name that uniquely identifies | Path | String | | | | |\r
+| | your subscriber's | | | | Y | | CG1 |\r
++-------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-------------------------------------------------+\r
+| consumerId | Within your subscriber's group, | | | | | | |\r
+| | a name that uniquely identifies | Path | String | | y | | C1 |\r
+| | your subscriber's process | | | | | | | \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
+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
+| Name | Description | Type | Format | Valid/Example Values |\r
++==================+================================+============+==============+===========================================================+\r
+| httpStatusCode | | | | 200, 201 etc. |\r
++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+\r
+| mrErrorCode | Numeric error code | | | 200, 201 etc. |\r
++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+\r
+| errorMessage | | | | SUCCESS, or error message. |\r
++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+\r
+| helpURL | helpurl | | | |\r
++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+\r
+| tranactionid | transaction-id value | | | 28-12-2015::08:18:50:682::135.25.227.66::28122015552391 |\r
++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+\r
+| ResponseBody | Messages consumed from topic | Json | Json | |\r
++------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+\r
+\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
+\r
++-------------------------+-----------------+----------------------------+----------------------------------------------------------------------------------------------------+\r
+| Error code | HTTP Code | Description |Issue reason |\r
++-------------------------+-----------------+----------------------------+----------------------------------------------------------------------------------------------------+\r
+| DMaaP\_MR\_ERR\_3008 | 413 | Request Entity too large | Message size exceeds the batch limit <limit>.Reduce the batch size and try again | +-------------------------+-----------------+----------------------------+----------------------------------------------------------------------------------------------------+\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
+\r
+\r
+\r
Code Review / dmaap / messagerouter / messageservice.git / commitdiff