docs/offeredapis/api.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 Offered APIs
   5 ~~~~~~~~~~~~
   6
   7 .. toctree::
   8     :maxdepth: 3
   9
  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.
  15
  16 General HTTP Requirements
  17 -------------------------
  18
  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.
  23
  24 HTTP URL
  25 --------
  26
  27 http[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
  33 HTTP Header
  34 -----------
  35
  36 Specifies HTTP Headers, such as Content-Type, that define the parameters
  37 of the HTTP Transaction
  38
  39 HTTP Body
  40 ---------
  41
  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.
  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 |
  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 +-------------------------+-----------------------------------------------------------------------------------------------------------------+
  62
  63 Publishers
  64 -----------
  65
  66 **Description**: Publishes data to Kafka server on the topic mentioned in the URL.
  67 Messages will be in the request body
  68
  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
  73 broker itself.
  74
  75 Request URL
  76 ===========
  77
  78 POST http(s)://{HOST:PORT}/events/{topicname}
  79
  80 Request 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
  97
  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
 101
 102
 103 Response 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
 122 Response /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 +========================+===============+=================================+=========================================================================================================+
 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 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
 152
 153 Sample 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
 172 Sample 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
 191 Subscribers
 192 -----------
 193 **Description**: To subscribe to a MessageRouter topic, a subscriber issues a GET to the RESTful HTTP endpoint for events.
 194
 195 Request URL:
 196 ============
 197
 198 GET http(s)://{HOST:PORT}}/events/{topicname}/{consumergroup}/{consumerid}/{timeout=x}
 199
 200 Request Parameters:
 201 ===================
 202
 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 +---------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
 222
 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
 226
 227 Response 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 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 241 | transactionid    | transaction-id value           |            |              | 28-12-2015::08:18:50:682::<IP>::28122015552391            |
 242 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 243 | ResponseBody     | Messages consumed from topic   | Json       | Json         |                                                           |
 244 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 245
 246
 247 Response /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
 278 Sample Request:
 279 ===============
 280
 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 +-----------------------------------------------------------------------------+
 294
 295 Provisioning
 296 ------------
 297
 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
 300
 301 Create Topic
 302 ============
 303 Request URL:
 304 ============
 305
 306 POST http(s)://{HOST:PORT}/topics/create
 307
 308 Request Parameters:
 309 ===================
 310
 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 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
 327
 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
 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
 356 Response 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
 375 Sample Request:
 376 ===============
 377
 378  .. code:: bash
 379
 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": []
 398
 399
 400 GetTopic Details
 401 ----------------
 402
 403 Request URL
 404 ===========
 405
 406 GET http(s)://{HOST:PORT}/topics    : To list the details of all the topics in Message Router.
 407
 408 GET http(s)://{HOST:PORT}/topics/{topicname} : To list the details of a specified topic.
 409
 410 Request Parameters
 411 ==================
 412
 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 +--------------------------+-------------------------+------------------+------------+-----------+-------------+-----------------+-----------------------------+
 418
 419 **NOTE**: To view an authenticated topic, user must have the AAF permission
 420  org.onap.dmaap.mr.topic|*|view
 421
 422
 423 Response 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
 450 Sample Request:
 451 ===============
 452
 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                                                                                               |
 457 |    {"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"                                     |
 460 |    ]},                                                                                                                            |
 461 +-----------------------------------------------------------------------------------------------------------------------------------+
 462
 463
 464 Delete Topics
 465 -------------
 466
 467 Request URL:
 468 ============
 469
 470 DELETE http(s)://{HOST:PORT}/topics/{topicname}
 471
 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
 474
 475 Sample Request:
 476 ===============
 477 ex: http ://<hostname>:3904/topics/org.onap.dmaap.mr.testopic
 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
 495 API 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 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
 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 +-----------+--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+