1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
10 DMaaP Message Router utilizes an HTTP REST API to service all Publish
11 and Consume transactions. HTTP and REST standards are followed so
12 clients as varied as cURL, Java applications and even Web Browsers will
13 work to interact with Message Router. Message Router uses AAF for user's
14 authentication and authorization.
16 General HTTP Requirements
17 -------------------------
19 A DMaaP Message Router transaction consists of 4 distinct segments:
20 HTTP URL, HTTP Header, HTTP Body (POST) and HTTP Response. The general
21 considerations for each segment are as follows and are required for each
22 of the specific transactions described in this section.
27 http[s]://serverBaseURL{/routing}{resourcePath}
29 - The serverBaseURL points to DMaaP Message Router host/port that will service the request.
31 - The resourcePath specifies the specific service, or Topic, that the client is attempting to reach
36 Specifies HTTP Headers, such as Content-Type, that define the parameters
37 of the HTTP Transaction
42 The HTTP Body contains the topic content when Publishing or Consuming.
43 The Body may contain topic messages in several formats (like below) but
44 it must be noted, that, except in very specific circumstances, messages
45 are not inspected for content.
48 +-------------------------+-----------------------------------------------------------------------------------------------------------------+
49 | Content-Type | Description |
50 +=========================+=================================================================================================================+
51 | text/plain | Each line in the POST body is treated as a separate message. No partition key is specified, and therefore no |
52 | | order is guaranteed. This format is mainly for test, as messages are highly likely to be re-ordered when |
53 | | delivered through the Kafka cluster. |
54 +-------------------------+-----------------------------------------------------------------------------------------------------------------+
55 | application/json | The payload maybe a single JSON object or a JSON array of JSON objects. Each object is handled as an individual |
56 | | message. Note that use of this format may result in equivalent but altered JSON objects sent to consumers. |
57 | | That's because MR uses a standard JSON parser to read each object into memory before pushing the object to the |
58 | | Kafka system. At that point, the JSON object is re-written from the in-memory object. This can result in |
59 | | re-ordered fields or changes in whitespace. If you want to preserve JSON objects exactly, |
60 | | use application/cambria. Following the JSON format is recommended. |
61 +-------------------------+-----------------------------------------------------------------------------------------------------------------+
66 **Description**: Publishes data to Kafka server on the topic mentioned in the URL.
67 Messages will be in the request body
69 The MessageRouter service has no requirements on what publishers can put
70 onto a topic. The messages are opaque to the service and are treated as
71 raw bytes. In general, passing JSON messages is preferred, but this is
72 due to higher-level features and related systems, not the MessageRouter
78 POST http(s)://{HOST:PORT}/events/{topicname}
83 +--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+
84 | Name | Description | Param Type | Data type | Max Len | Required | Format | Valid/EXample values |
85 +====================+==============================+==================+============+===========+=============+================================+=============================+
86 | Topicname | topic name to be posted | Path | String | 40 | Y | | org.onap.dmaap.mr.testtopic |
87 +--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+
88 | content-type | To specify type of message | Header | String | 20 | N | | application/json |
89 +--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+
90 | Username | userid | Header | String | | N | Basic Authentication Header | |
91 +--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+
92 | Password | | Header | String | | N | Basic Authentication Header | |
93 +--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+
94 | partitionKey | | QueryParam | String | | N | String value | ?Partitionkey=123 |
95 +--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+
98 **NOTE**: To publish data to the authenticated topic, Publisher must
99 have the AAF permission org.onap.dmaap.mr.topic|:topic.<topic name>|pub.
100 Publishers may use DMaaP BusController for provisoning the AAF permissions
106 +------------------+------------------------+------------+--------------+------------------------------+
107 | Name | Description | Type | Format | Valid/Example Values |
108 +==================+========================+============+==============+==============================+
109 | httpStatusCode | | | | 200, 201 etc. |
110 +------------------+------------------------+------------+--------------+------------------------------+
111 | mrErrorCode | Numeric error code | | | 200, 201 etc. |
112 +------------------+------------------------+------------+--------------+------------------------------+
113 | errorMessage | | | | SUCCESS, or error message. |
114 +------------------+------------------------+------------+--------------+------------------------------+
115 | helpURL | helpurl | | | |
116 +------------------+------------------------+------------+--------------+------------------------------+
117 | transactionid | transaction-id value | | | |
118 +------------------+------------------------+------------+--------------+------------------------------+
122 Response /Error Codes
123 =====================
125 +---------------------------+------------------------------------+
126 | Response statusCode | Response statusMessage |
127 +===========================+====================================+
128 | 200-299 | Success |
129 +---------------------------+------------------------------------+
130 | 400-499 | the client request has a problem |
131 +---------------------------+------------------------------------+
132 | 500-599 | the DMaaP service has a problem |
133 +---------------------------+------------------------------------+
135 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
136 | Error code | HTTPCode | Description | Issue Reason |
137 +========================+===============+=================================+=========================================================================================================+
138 | DMaaP\_MR\_ERR\_3001 | 413 | Request Entity too large | Message size exceeds the batch limit <limit>. Reduce the batch size and try again |
139 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
140 | DMaaP\_MR\_ERR\_3002 | 500 | Internal Server Error | Unable to publish messages. Please contact administrator |
141 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
142 | DMaaP\_MR\_ERR\_3003 | 400 | Bad Request | Incorrect Batching format. Please correct the batching format and try again |
143 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
144 | DMaaP\_MR\_ERR\_3004 | 413 | Request Entity too large | Message size exceeds the message size limit <limit>. Reduce the message size and try again |
145 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
146 | DMaaP\_MR\_ERR\_3005 | 400 | Bad Request | Incorrect JSON object. Please correct the JSON format and try again |
147 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
148 | DMaaP\_MR\_ERR\_3006 | 504 | Network Connect Timeout Error | Connection to the DMaaP MR was timed out. Please try again |
149 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
150 | DMaaP\_MR\_ERR\_3007 | 500 | Internal Server Error | Failed to publish messages to topic <topicName>. Successfully published <count > number of messages. |
151 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
156 +-----------------------------------------------------------------------------------+
159 | *Payload-* *{"message":"message description"}* *Content-Type: application/json* |
163 | curl -u XXXX@abc.com:X -H 'Content-Type:text/plain' -X POST -d @sampleMsg.txt |
167 | "serverTimeMs": 19" |
170 +-----------------------------------------------------------------------------------+
175 +---------------------------------------------------------------------+
178 | Server: Apache-Coyote/1.1 |
180 | transactionId: 28-12-2015::08:18:50:682::<IP>::28122015552391 |
182 | Content-Type: application/json |
184 | Content-Length: 42 |
186 | Date: Mon, 28 Dec 2015 13:18:50 GMT |
187 +---------------------------------------------------------------------+
193 **Description**: To subscribe to a MessageRouter topic, a subscriber issues a GET to the RESTful HTTP endpoint for events.
198 GET http(s)://{HOST:PORT}}/events/{topicname}/{consumergroup}/{consumerid}/{timeout=x}
203 +---------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
204 | Name | Description | Param Type | data type | MaxLen | Required | Format | Valid/Example Values |
205 +===============+=================================+==================+============+==============+=============+=====================+========================+
206 | topicname | Topic name to be posted | Path | String | 40 | Y | | |
207 +---------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
208 | consumergroup | A name that uniquely identifies | Path | String | | Y | | CG1 |
209 | | your subscribers | | | | | | |
210 +---------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
211 | consumerid | Within your subscribers group, | Path | String | | Y | | C1 |
212 | | a name that uniquely identifies | | | | | | |
213 | | your subscribers process | | | | | | |
214 +---------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
215 | content-type | To specify type of message | Header | String | 20 | N | | application/json |
216 | | content(json, text or cambria) | | | | | | |
217 +---------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
218 | Username | userid | Header | String | 1 | N | | |
219 +---------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
220 | Password | | Header | String | 1 | N | | |
221 +---------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
223 **NOTE**: To read data from an authenticated topic, User must have the
224 AAF permission org.onap.dmaap.mr.topic|:topic.<topic name>|sub.
225 Subscribers may use DMaaP BusController for provisioning the permissions in AAF
230 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
231 | Name | Description | Type | Format | Valid/Example Values |
232 +==================+================================+============+==============+===========================================================+
233 | httpStatusCode | | | | 200, 201 etc. |
234 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
235 | mrErrorCode | Numeric error code | | | 200, 201 etc. |
236 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
237 | errorMessage | | | | SUCCESS, or error message. |
238 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
239 | helpURL | helpurl | | | |
240 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
241 | transactionid | transaction-id value | | | 28-12-2015::08:18:50:682::<IP>::28122015552391 |
242 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
243 | ResponseBody | Messages consumed from topic | Json | Json | |
244 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
247 Response /Error Codes
248 =====================
251 +---------------------------+------------------------------------+
252 | Response statusCode | Response statusMessage |
253 +===========================+====================================+
254 | 200-299 | Success |
255 +---------------------------+------------------------------------+
256 | 400-499 | the client request has a problem |
257 +---------------------------+------------------------------------+
258 | 500-599 | the DMaaP service has a problem |
259 +---------------------------+------------------------------------+
261 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
262 | Error code | HTTPCode | Description | Issue Reason |
263 +=========================+=================+============================+=============================================================================================+
264 | DMaaP\_MR\_ERR\_3008 | 413 | Request Entity too large | Message size exceeds the batch limit <limit>.Reduce the batch size and try again |
265 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
266 | DMaaP\_MR\_ERR\_3009 | 500 | Internal Server Error | Unable to publish messages. Please contact administrator |
267 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
268 | DMaaP\_MR\_ERR\_3010 | 400 | Bad Request | Incorrect Batching format. Please correct the batching format and try again |
269 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
270 | DMaaP\_MR\_ERR\_3011 | 413 | Request Entity too large | Message size exceeds the message size limit <limit>.Reduce the message size and try again |
271 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
272 | DMaaP\_MR\_ERR\_5012 | 429 | Too many requests | This client is making too many requests. Please use a long poll setting to decrease the |
273 | | | | number of requests that result in empty responses. |
274 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
275 | | 503 | Service Unavailable | Service Unavailable. |
276 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
281 +-----------------------------------------------------------------------------+
282 | GET http ://{hostname}:3904/events/org.onap.dmaap.mr.sprint/mygroup/mycus |
284 | Content-Type: application/json |
288 |curl -u XXX@csp.abc.com:MRDmap2016$ -X GET -d 'MyfirstMessage' |
290 |http ://10.12.7.22:3904/events/com.att.ecomp_test.crm.preDeo/myG/C1 |
292 |[I am r sending first msg,I am R sending first msg] |
293 +-----------------------------------------------------------------------------+
298 **Description**: To create, modify or delete the MessageRouter topics. These APIs can also be used by other applications to provision topics in MessageRouter.
299 DMaaP BusController is recommended for topic and AAF permissions provisioning
306 POST http(s)://{HOST:PORT}/topics/create
311 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
312 | Name | Description | Param Type | datatype | MaxLen | Required | Format | Valid/Example Values |
313 +===================+=================================+==================+============+==============+=============+=============+===================================+
314 | Topicname | topicname to be created in MR | Body | String | 20 | Y | Json | org.onap.dmaap.mr.metrics |
315 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
316 | topicDescription | description for topic | Body | String | 15 | Y | | |
317 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
318 | partitionCount | Kafka topic partition | Body | String | 1 | Y | | |
319 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
320 | replicationCount | Kafka topic replication | Body | String | 1 | Y | | 3 (Default -for 3 node Kafka ) |
321 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
322 | transaction | to create transaction id for | Body | Boolean | 1 | N | | true |
323 | Enabled | each message transaction | | | | | | |
324 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
325 | Content-Type | application/json | Header | String | | | | application/json |
326 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
328 **NOTE**: To Create an authenticated topic, user must have the AAF permission
329 org.onap.dmaap.mr.topicFactory|:org.onap.dmaap.mr.topic:org.onap.dmaap.mr|create
332 +---------------------------+------------------------------------+
333 | Response statusCode | Response statusMessage |
334 +===========================+====================================+
335 | 200-299 | Success |
336 +---------------------------+------------------------------------+
337 | 400-499 | the client request has a problem |
338 +---------------------------+------------------------------------+
339 | 500-599 | the DMaaP service has a problem |
340 +---------------------------+------------------------------------+
343 +-------------------------+-----------------+--------------------------------------------------+
344 | Error code | HTTP Code | Description |
345 +=========================+=================+==================================================+
346 | DMaaP\_MR\_ERR\_5001 | 500 | Failed to retrieve list of all topics |
347 +-------------------------+-----------------+--------------------------------------------------+
348 | DMaaP\_MR\_ERR\_5002 | 500 | Failed to retrieve details of topic:<topicName> |
349 +-------------------------+-----------------+--------------------------------------------------+
350 | DMaaP\_MR\_ERR\_5003 | 500 | Failed to create topic:<topicName> |
351 +-------------------------+-----------------+--------------------------------------------------+
352 | DMaaP\_MR\_ERR\_5004 | 500 | Failed to delete topic:<topicName> |
353 +-------------------------+-----------------+--------------------------------------------------+
359 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
360 | Name | Description | Type | Format | Valid/Example Values |
361 +==================+================================+============+==============+===========================================================+
362 | httpStatusCode | | | | 200, 201 etc. |
363 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
364 | mrErrorCode | Numeric error code | | | 5005 |
365 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
366 | errorMessage | | | | SUCCESS, or error message. |
367 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
368 | helpURL | helpurl | | | |
369 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
370 | ResponseBody | Topic details (owner, | Json | Json | |
371 | | trxEnabled=true) | | | |
372 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
380 POST http: //<hostname>:3904/topics/create
382 {"topicName":"org.onap.dmaap.mr.testtopic","description":"This is a test Topic ",
383 "partitionCount":"1","replicationCount":"3","transactionEnabled":"true"}
384 Content-Type: application/json
386 curl -u XXXc@csp.abc.com:xxxxx$ -H 'Content-Type:application/json' -X POST -d
387 @topicname.txt http: //message-router:3904/topics/create
393 "description": "This is a TestTopic",
394 "name": "org.onap.dmaap.mr.testtopic",
406 GET http(s)://{HOST:PORT}/topics : To list the details of all the topics in Message Router.
408 GET http(s)://{HOST:PORT}/topics/{topicname} : To list the details of a specified topic.
413 +--------------------------+-------------------------+------------------+------------+-----------+-------------+-----------------+-----------------------------+
414 | Name | Description | Param Type | Data type | Max Len | Required | Format | Valid/EXample values |
415 +==========================+=========================+==================+============+===========+=============+=================+=============================+
416 | topicname | topic name details | Body | String | 20 | Y | Json | org.onap.dmaap.mr.testtopic |
417 +--------------------------+-------------------------+------------------+------------+-----------+-------------+-----------------+-----------------------------+
419 **NOTE**: To view an authenticated topic, user must have the AAF permission
420 org.onap.dmaap.mr.topic|*|view
426 +------------------+------------------------+------------+----------+---------+----------------------------+
427 | Name | Description | ParamType | datatype |Format | Valid/Example Values |
428 +==================+========================+============+==========+=========+============================+
429 | topicname | topic name details | Body | String | Json | org.onap.dmaap.mr.testopic |
430 +------------------+------------------------+------------+----------+---------+----------------------------+
431 | description | | | String | | |
432 +------------------+------------------------+------------+----------+---------+----------------------------+
433 | owner |user id who created the | | | | |
435 +------------------+------------------------+------------+----------+---------+----------------------------+
436 | txenabled | true or false | | boolean | | |
437 +------------------+------------------------+------------+----------+---------+----------------------------+
439 +---------------------------+------------------------------------+
440 | Response statusCode | Response statusMessage |
441 +===========================+====================================+
442 | 200-299 | Success |
443 +---------------------------+------------------------------------+
444 | 400-499 | the client request has a problem |
445 +---------------------------+------------------------------------+
446 | 500-599 | the DMaaP service has a problem |
447 +---------------------------+------------------------------------+
453 +-----------------------------------------------------------------------------------------------------------------------------------+
454 | GET http ://<hostname>:3904/topic/org.onap.dmaap.mr.testtopic |
455 | curl -u XXX@csp.abc.com:x$ -X |
456 | GET http ://10.12.7.22:3904/topics |
458 | {"txenabled": true,"description": "This is a TestTopic","owner": "XXXX@csp.abc.com","topicName": "org.onap.dmaap.mr.Load9" |
459 | {"txenabled": false,"description": "", "owner": "", "topicName": "org.onap.dmaap.mr.Load1" |
461 +-----------------------------------------------------------------------------------------------------------------------------------+
470 DELETE http(s)://{HOST:PORT}/topics/{topicname}
472 **NOTE**: To delete a topic, user must have the AAF permission
473 org.onap.dmaap.mr.topicFactory|:org.onap.dmaap.mr.topic:org.onap.dmaap.mr|destroy
477 ex: http ://<hostname>:3904/topics/org.onap.dmaap.mr.testopic
479 +---------------------------+------------------------------------+
480 | Response statusCode | Response statusMessage |
481 +===========================+====================================+
482 | 200-299 | Success |
483 +---------------------------+------------------------------------+
484 | 400-499 | the client request has a problem |
485 +---------------------------+------------------------------------+
486 | 500-599 | the DMaaP service has a problem |
487 +---------------------------+------------------------------------+
489 +-------------------------+---------------------------------------------+----------------------+
490 | Error code | Description |HTTP code |
491 +=========================+=============================================+======================+
492 | DMaaP\_MR\_ERR\_5004 | Failed to delete topic:<topicName> | 500 |
493 +-------------------------+---------------------------------------------+----------------------+
498 +-----------+--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
499 | | API Name | API Method | REST API Path | | Comments |
500 +===========+====================+=========================================+=======================================+================+==================================+
501 | Topics | GetAll Topics | getTopics() | /topics | GET | |
503 | +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
504 | | Get All Topics | | | | |
505 | | List with details | getAllTopics() | /topics/listAll | GET | |
506 | +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
507 | | Get individual | | | | |
508 | | Topic Details | getTopic(String topicName) | /topics/{topicName} | GET | |
509 | +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
510 | | Create Topic | createTopic(TopicBean topicBean) | /topics/create | POST | |
511 | +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
512 | | Delete Topic | deleteTopic(String topicName) | /topics/{topicName} | DELETE | Not used in current MR version |
513 | +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
514 | | Get Publishers | getPublishersByTopicName | | | |
515 | | for a Topic | (String topicName) | /topics/{topicName}/producers | GET | UEB Backward Compatibility |
516 | +--------------------+-----------------------------------------+---------------------------------------+----------------+ |
517 | | Add a Publisher | permitPublisherForTopic | /topics/{topicName}/producers/ | PUT | |
518 | | to write ACL on | (String topicName, String producerId) | {producerId} | | |
519 | | a Topic | | | | |
520 | +--------------------+-----------------------------------------+---------------------------------------+----------------+ |
521 | | Remove a Publisher | denyPublisherForTopic(String topicName, | /topics/{topicName}/producers/ | DELETE | |
522 | | from write ACL on | String producerId) | {producerId} | | |
523 | | a Topic | | | | |
524 | +--------------------+-----------------------------------------+---------------------------------------+----------------+ |
525 | | Get Consumers for | getConsumersByTopicName | /topics/{topicName}/consumers | GET | |
526 | | a Topic | (String topicName) | | | |
527 | +--------------------+-----------------------------------------+---------------------------------------+----------------+ |
528 | | Add a Consumer | permitConsumerForTopic(String | /topics/{topicName}/consumers/ | PUT | |
529 | | to read ACL | topicName, String consumerId) | {consumerId} | | |
530 | | on a Topic | | | | |
531 | +--------------------+-----------------------------------------+---------------------------------------+----------------+ |
532 | | Remove a consumer | denyPublisherForTopic(String topicName, | /topics/{topicName}/consumers/ | DELETE | |
533 | | from write | String consumerId) | {consumerId} | | |
534 | | ACL on a Topic | | | | |
535 +-----------+--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+