Gitiles
Code Review Sign In
gerrit.nordix.org / onap / dmaap / messagerouter / messageservice / 89701dc6483800daef21eac3feafd4f74553f238 / . / docs / offeredapis / api.rst
blob: 6027acf80e69d13ea745c553390f13214f30ff48 [file] [log] [blame]
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]1.. This work is licensed under a Creative Commons Attribution 4.0 International License.
2.. http://creativecommons.org/licenses/by/4.0
3
4Offered APIs
5~~~~~~~~~~~~
6
7.. toctree::
8 :maxdepth: 3
9
10DMaaP Message Router utilizes an HTTP REST API to service all Publish
11and Consume transactions. HTTP and REST standards are followed so
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]12clients as varied as cURL, Java applications and even Web Browsers will
13work to interact with Message Router. Message Router uses AAF for user's
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]14authentication and authorization.
15
16General HTTP Requirements
17-------------------------
18
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]19A DMaaP Message Router transaction consists of 4 distinct segments:
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]20HTTP URL, HTTP Header, HTTP Body (POST) and HTTP Response. The general
21considerations for each segment are as follows and are required for each
22of the specific transactions described in this section.
23
24HTTP URL
efiacor89701dc2022-11-07 09:16:55 +0000[diff] [blame^]25--------
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]26
27http[s]://serverBaseURL{/routing}{resourcePath}
28
29- The serverBaseURL points to DMaaP Message Router host/port that will service the request.
30
31- The resourcePath specifies the specific service, or Topic, that the client is attempting to reach
32
33HTTP Header
34-----------
35
36Specifies HTTP Headers, such as Content-Type, that define the parameters
37of the HTTP Transaction
38
39HTTP Body
40---------
41
42The HTTP Body contains the topic content when Publishing or Consuming.
43The Body may contain topic messages in several formats (like below) but
44it must be noted, that, except in very specific circumstances, messages
45are not inspected for content.
46
47
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 |
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]56| | message. Note that use of this format may result in equivalent but altered JSON objects sent to consumers. |
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]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, |
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]60| | use application/cambria. Following the JSON format is recommended. |
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]61+-------------------------+-----------------------------------------------------------------------------------------------------------------+
62
63Publishers
64-----------
65
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]66**Description**: Publishes data to Kafka server on the topic mentioned in the URL.
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]67Messages will be in the request body
68
69The MessageRouter service has no requirements on what publishers can put
70onto a topic. The messages are opaque to the service and are treated as
71raw bytes. In general, passing JSON messages is preferred, but this is
72due to higher-level features and related systems, not the MessageRouter
73broker itself.
74
75Request URL
76===========
77
78POST http(s)://{HOST:PORT}/events/{topicname}
79
80Request Parameters
81==================
82
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+--------------------+------------------------------+------------------+------------+-----------+-------------+--------------------------------+-----------------------------+
96
efiacor89701dc2022-11-07 09:16:55 +0000[diff] [blame^]97
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]98**NOTE**: To publish data to the authenticated topic, Publisher must
efiacor89701dc2022-11-07 09:16:55 +0000[diff] [blame^]99have the AAF permission org.onap.dmaap.mr.topic|:topic.<topic name>|pub.
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]100Publishers may use DMaaP BusController for provisoning the AAF permissions
101
efiacor89701dc2022-11-07 09:16:55 +0000[diff] [blame^]102
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]103Response Parameters
104===================
105
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+------------------+------------------------+------------+--------------+------------------------------+
119
120
121
122Response /Error Codes
123=====================
124
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+---------------------------+------------------------------------+
134
135+------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
136| Error code | HTTPCode | Description | Issue Reason |
137+========================+===============+=================================+=========================================================================================================+
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]138| DMaaP\_MR\_ERR\_3001 | 413 | Request Entity too large | Message size exceeds the batch limit <limit>. Reduce the batch size and try again |
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]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+------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]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 |
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]145+------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
146| DMaaP\_MR\_ERR\_3005 | 400 | Bad Request | Incorrect JSON object. Please correct the JSON format and try again |
147+------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]148| DMaaP\_MR\_ERR\_3006 | 504 | Network Connect Timeout Error | Connection to the DMaaP MR was timed out. Please try again |
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]149+------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
150| DMaaP\_MR\_ERR\_3007 | 500 | Internal Server Error | Failed to publish messages to topic <topicName>. Successfully published <count > number of messages. |
151+------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
152
153Sample Request:
154===============
155
156+-----------------------------------------------------------------------------------+
157| POST |
158| |
159| *Payload-* *{"message":"message description"}* *Content-Type: application/json* |
160| |
161| Example: |
162| |
163| curl -u XXXX@abc.com:X -H 'Content-Type:text/plain' -X POST -d @sampleMsg.txt |
164| |
165| { "count": 1, |
166| |
167| "serverTimeMs": 19" |
168| |
169| } |
170+-----------------------------------------------------------------------------------+
171
172Sample Response:
173================
174
175+---------------------------------------------------------------------+
176| HTTP/1.1 200 OK |
177| |
178| Server: Apache-Coyote/1.1 |
179| |
180| transactionId: 28-12-2015::08:18:50:682::<IP>::28122015552391 |
181| |
182| Content-Type: application/json |
183| |
184| Content-Length: 42 |
185| |
186| Date: Mon, 28 Dec 2015 13:18:50 GMT |
187+---------------------------------------------------------------------+
188
189
190
191Subscribers
192-----------
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]193**Description**: To subscribe to a MessageRouter topic, a subscriber issues a GET to the RESTful HTTP endpoint for events.
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]194
195Request URL:
196============
197
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]198GET http(s)://{HOST:PORT}}/events/{topicname}/{consumergroup}/{consumerid}/{timeout=x}
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]199
200Request Parameters:
201===================
202
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]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+---------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]222
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]223**NOTE**: To read data from an authenticated topic, User must have the
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]224AAF permission org.onap.dmaap.mr.topic|:topic.<topic name>|sub.
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]225Subscribers may use DMaaP BusController for provisioning the permissions in AAF
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]226
227Response Parameters:
228====================
229
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+------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]241| transactionid | transaction-id value | | | 28-12-2015::08:18:50:682::<IP>::28122015552391 |
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]242+------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
243| ResponseBody | Messages consumed from topic | Json | Json | |
244+------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
245
246
247Response /Error Codes
248=====================
249
250
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+---------------------------+------------------------------------+
260
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+-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
277
278Sample Request:
279===============
280
efiacor89701dc2022-11-07 09:16:55 +0000[diff] [blame^]281+-----------------------------------------------------------------------------+
282| GET http ://{hostname}:3904/events/org.onap.dmaap.mr.sprint/mygroup/mycus |
283| |
284| Content-Type: application/json |
285| |
286| Example: |
287| |
288|curl -u XXX@csp.abc.com:MRDmap2016$ -X GET -d 'MyfirstMessage' |
289| |
290|http ://10.12.7.22:3904/events/com.att.ecomp_test.crm.preDeo/myG/C1 |
291| |
292|[I am r sending first msg,I am R sending first msg] |
293+-----------------------------------------------------------------------------+
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]294
295Provisioning
296------------
efiacor89701dc2022-11-07 09:16:55 +0000[diff] [blame^]297
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]298**Description**: To create, modify or delete the MessageRouter topics. These APIs can also be used by other applications to provision topics in MessageRouter.
299DMaaP BusController is recommended for topic and AAF permissions provisioning
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]300
301Create Topic
302============
303Request URL:
304============
305
306POST http(s)://{HOST:PORT}/topics/create
307
308Request Parameters:
309===================
310
311+-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
312| Name | Description | Param Type | datatype | MaxLen | Required | Format | Valid/Example Values |
313+===================+=================================+==================+============+==============+=============+=============+===================================+
efiacor89701dc2022-11-07 09:16:55 +0000[diff] [blame^]314| Topicname | topicname to be created in MR | Body | String | 20 | Y | Json | org.onap.dmaap.mr.metrics |
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]315+-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
316| topicDescription | description for topic | Body | String | 15 | Y | | |
317+-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]318| partitionCount | Kafka topic partition | Body | String | 1 | Y | | |
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]319+-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]320| replicationCount | Kafka topic replication | Body | String | 1 | Y | | 3 (Default -for 3 node Kafka ) |
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]321+-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]322| transaction | to create transaction id for | Body | Boolean | 1 | N | | true |
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]323| Enabled | each message transaction | | | | | | |
324+-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
325| Content-Type | application/json | Header | String | | | | application/json |
326+-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
327
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]328**NOTE**: To Create an authenticated topic, user must have the AAF permission
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]329 org.onap.dmaap.mr.topicFactory|:org.onap.dmaap.mr.topic:org.onap.dmaap.mr|create
330
331
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+---------------------------+------------------------------------+
341
342
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+-------------------------+-----------------+--------------------------------------------------+
354
355
356Response Parameters
357====================
358
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+------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
373
374
375Sample Request:
376===============
377
efiacor89701dc2022-11-07 09:16:55 +0000[diff] [blame^]378 .. code:: bash
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]379
efiacor89701dc2022-11-07 09:16:55 +0000[diff] [blame^]380 POST http: //<hostname>:3904/topics/create
381 Request Body
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
385 Example:
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
388 {
389 "writerAcl": {
390 "enabled": false,
391 "users": []
392 },
393 "description": "This is a TestTopic",
394 "name": "org.onap.dmaap.mr.testtopic",
395 "readerAcl": {
396 "enabled": false,
397 "users": []
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]398
399
400GetTopic Details
401----------------
402
403Request URL
404===========
405
406GET http(s)://{HOST:PORT}/topics : To list the details of all the topics in Message Router.
407
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]408GET http(s)://{HOST:PORT}/topics/{topicname} : To list the details of a specified topic.
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]409
410Request Parameters
411==================
412
413+--------------------------+-------------------------+------------------+------------+-----------+-------------+-----------------+-----------------------------+
414| Name | Description | Param Type | Data type | Max Len | Required | Format | Valid/EXample values |
415+==========================+=========================+==================+============+===========+=============+=================+=============================+
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]416| topicname | topic name details | Body | String | 20 | Y | Json | org.onap.dmaap.mr.testtopic |
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]417+--------------------------+-------------------------+------------------+------------+-----------+-------------+-----------------+-----------------------------+
418
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]419**NOTE**: To view an authenticated topic, user must have the AAF permission
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]420 org.onap.dmaap.mr.topic|*|view
421
422
423Response Parameters
424====================
425
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 | | | | |
434| | topic | | | | |
435+------------------+------------------------+------------+----------+---------+----------------------------+
436| txenabled | true or false | | boolean | | |
437+------------------+------------------------+------------+----------+---------+----------------------------+
438
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+---------------------------+------------------------------------+
448
449
450Sample Request:
451===============
452
453+-----------------------------------------------------------------------------------------------------------------------------------+
efiacor89701dc2022-11-07 09:16:55 +0000[diff] [blame^]454| GET http ://<hostname>:3904/topic/org.onap.dmaap.mr.testtopic |
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]455| curl -u XXX@csp.abc.com:x$ -X |
efiacor89701dc2022-11-07 09:16:55 +0000[diff] [blame^]456| GET http ://10.12.7.22:3904/topics |
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]457| {"topics": [ |
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]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" |
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]460| ]}, |
461+-----------------------------------------------------------------------------------------------------------------------------------+
462
463
464Delete Topics
465-------------
466
467Request URL:
468============
469
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]470DELETE http(s)://{HOST:PORT}/topics/{topicname}
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]471
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]472**NOTE**: To delete a topic, user must have the AAF permission
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]473org.onap.dmaap.mr.topicFactory|:org.onap.dmaap.mr.topic:org.onap.dmaap.mr|destroy
474
475Sample Request:
476===============
efiacor89701dc2022-11-07 09:16:55 +0000[diff] [blame^]477ex: http ://<hostname>:3904/topics/org.onap.dmaap.mr.testopic
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]478
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+---------------------------+------------------------------------+
488
489+-------------------------+---------------------------------------------+----------------------+
490| Error code | Description |HTTP code |
491+=========================+=============================================+======================+
492| DMaaP\_MR\_ERR\_5004 | Failed to delete topic:<topicName> | 500 |
493+-------------------------+---------------------------------------------+----------------------+
494
495API Inventory
496-------------
497
498+-----------+--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
499| | API Name | API Method | REST API Path | | Comments |
500+===========+====================+=========================================+=======================================+================+==================================+
501| Topics | GetAll Topics | getTopics() | /topics | GET | |
502| | List | | | | |
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| +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]512| | Delete Topic | deleteTopic(String topicName) | /topics/{topicName} | DELETE | Not used in current MR version |
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]513| +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
514| | Get Publishers | getPublishersByTopicName | | | |
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]515| | for a Topic | (String topicName) | /topics/{topicName}/producers | GET | UEB Backward Compatibility |
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]516| +--------------------+-----------------------------------------+---------------------------------------+----------------+ |
517| | Add a Publisher | permitPublisherForTopic | /topics/{topicName}/producers/ | PUT | |
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]518| | to write ACL on | (String topicName, String producerId) | {producerId} | | |
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]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 | |
Lasse Kaihlavirtabb7fe8c2021-02-05 17:27:03 +0200[diff] [blame]529| | to read ACL | topicName, String consumerId) | {consumerId} | | |
sunil.unnava23f58b62019-04-25 17:41:10 -0400[diff] [blame]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+-----------+--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+