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 transactions 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. Recommended to follow the JSON format.                                                 |
  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 **NOTE**: To publish data to the authenticated topic, Publisher must
  98  have the AAF permission org.onap.dmaap.mr.topic|:topic.<topic name>|pub.
  99 Publishers may use DMaaP BusController for provisoning the AAF permissions
 100
 101 Response Parameters
 102 ===================
 103
 104 +------------------+------------------------+------------+--------------+------------------------------+
 105 | Name             | Description            | Type       | Format       | Valid/Example Values         |
 106 +==================+========================+============+==============+==============================+
 107 | httpStatusCode   |                        |            |              | 200, 201 etc.                |
 108 +------------------+------------------------+------------+--------------+------------------------------+
 109 | mrErrorCode      | Numeric error code     |            |              | 200, 201 etc.                |
 110 +------------------+------------------------+------------+--------------+------------------------------+
 111 | errorMessage     |                        |            |              | SUCCESS, or error message.   |
 112 +------------------+------------------------+------------+--------------+------------------------------+
 113 | helpURL          | helpurl                |            |              |                              |
 114 +------------------+------------------------+------------+--------------+------------------------------+
 115 | transactionid    | transaction-id value   |            |              |                              |
 116 +------------------+------------------------+------------+--------------+------------------------------+
 117
 118
 119
 120 Response /Error Codes
 121 =====================
 122
 123 +---------------------------+------------------------------------+
 124 | Response statusCode       |  Response statusMessage            |
 125 +===========================+====================================+
 126 | 200-299                   | Success                            |
 127 +---------------------------+------------------------------------+
 128 | 400-499                   | the client request has a problem   |
 129 +---------------------------+------------------------------------+
 130 | 500-599                   | the DMaaP service has a problem    |
 131 +---------------------------+------------------------------------+
 132
 133 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
 134 | Error code             |  HTTPCode     |  Description                    | Issue Reason                                                                                            |
 135 +========================+===============+=================================+=========================================================================================================+
 136 | DMaaP\_MR\_ERR\_3001   | 413           | Request Entity too large        | Message size exceeds the batch limit <limit>.Reduce the batch size and try again                        |
 137 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
 138 | DMaaP\_MR\_ERR\_3002   | 500           | Internal Server Error           | Unable to publish messages. Please contact administrator                                                |
 139 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
 140 | DMaaP\_MR\_ERR\_3003   | 400           | Bad Request                     | Incorrect Batching format. Please correct the batching format and try again                             |
 141 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
 142 | DMaaP\_MR\_ERR\_3004   | 413           | Request Entity too large        | Message size exceeds the message size limit <limit>.Reduce the message size and try again               |
 143 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
 144 | DMaaP\_MR\_ERR\_3005   | 400           | Bad Request                     | Incorrect JSON object. Please correct the JSON format and try again                                     |
 145 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
 146 | DMaaP\_MR\_ERR\_3006   | 504           | Network Connect Timeout Error   | Connection to the DMaaP MR was timed out.Please try again                                               |
 147 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
 148 | DMaaP\_MR\_ERR\_3007   | 500           | Internal Server Error           | Failed to publish  messages to topic <topicName>. Successfully published <count > number of messages.   |
 149 +------------------------+---------------+---------------------------------+---------------------------------------------------------------------------------------------------------+
 150
 151 Sample Request:
 152 ===============
 153
 154 +-----------------------------------------------------------------------------------+
 155 | POST                                                                              |
 156 |                                                                                   |
 157 | *Payload-* *{"message":"message description"}* *Content-Type: application/json*   |
 158 |                                                                                   |
 159 | Example:                                                                          |
 160 |                                                                                   |
 161 | curl -u XXXX@abc.com:X -H 'Content-Type:text/plain' -X POST -d @sampleMsg.txt     |
 162 |                                                                                   |
 163 | {    "count": 1,                                                                  |
 164 |                                                                                   |
 165 |     "serverTimeMs": 19"                                                           |
 166 |                                                                                   |
 167 | }                                                                                 |
 168 +-----------------------------------------------------------------------------------+
 169
 170 Sample Response:
 171 ================
 172
 173 +---------------------------------------------------------------------+
 174 | HTTP/1.1 200 OK                                                     |
 175 |                                                                     |
 176 |     Server: Apache-Coyote/1.1                                       |
 177 |                                                                     |
 178 |     transactionId: 28-12-2015::08:18:50:682::<IP>::28122015552391   |
 179 |                                                                     |
 180 |     Content-Type: application/json                                  |
 181 |                                                                     |
 182 |     Content-Length: 42                                              |
 183 |                                                                     |
 184 |     Date: Mon, 28 Dec 2015 13:18:50 GMT                             |
 185 +---------------------------------------------------------------------+
 186
 187
 188
 189 Subscribers
 190 -----------
 191 **Description**:To subscribe to a MessageRouter topic, a subscriber issues a GET to the RESTful HTTP endpoint for events.
 192
 193 Request URL:
 194 ============
 195
 196 GET http(s)://{HOST:PORT}}/events/{topicname}/{consumegroup}/{consumerid}/{timeout=x}
 197
 198 Request Parameters:
 199 ===================
 200
 201 +--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
 202 | Name         | Description                     |  Param Type      |  data type |   MaxLen     |  Required   |  Format             |  Valid/Example Values  |
 203 +==============+=================================+==================+============+==============+=============+=====================+========================+
 204 | Topicname    | topic name to be posted         |     Path         |   String   |    40        |     Y       |                     |                        |
 205 +--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
 206 | Consumer     | A name that uniquely identifies |     Path         |   String   |              |     Y       |                     | CG1                    |
 207 | group        | your subscribers                |                  |            |              |             |                     |                        |
 208 +--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
 209 | consumerId   | Within your subscribers group,  |     Path         |   String   |              |     Y       |                     | C1                     |
 210 |              | a name that uniquely identifies |                  |            |              |             |                     |                        |
 211 |              | your subscribers  process       |                  |            |              |             |                     |                        |
 212 +--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
 213 | content-type | To specify type of message      |     Header       |   String   |     20       |     N       |                     | aplication/json        |
 214 |              | content(json,text or cambria)   |                  |            |              |             |                     |                        |
 215 +--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
 216 | Username     | userid                          |     Header       |   String   |     1        |     N       |                     |                        |
 217 +--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
 218 | Password     |                                 |     Header       |   String   |     1        |     N       |                     |                        |
 219 +--------------+---------------------------------+------------------+------------+--------------+-------------+---------------------+------------------------+
 220
 221 **NOTE**:To read data from a authenticated topic, User must have the
 222 AAF permission org.onap.dmaap.mr.topic|:topic.<topic name>|sub.
 223 Subscribers may use DMaaP BusController for provisoning the permissions in AAF
 224
 225 Response Parameters:
 226 ====================
 227
 228 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 229 | Name             | Description                    |  Type      | Format       | Valid/Example Values                                      |
 230 +==================+================================+============+==============+===========================================================+
 231 | httpStatusCode   |                                |            |              | 200, 201 etc.                                             |
 232 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 233 | mrErrorCode      | Numeric error code             |            |              | 200, 201 etc.                                             |
 234 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 235 | errorMessage     |                                |            |              | SUCCESS, or error message.                                |
 236 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 237 | helpURL          | helpurl                        |            |              |                                                           |
 238 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 239 | tranactionid     | transaction-id value           |            |              | 28-12-2015::08:18:50:682::135.25.227.66::28122015552391   |
 240 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 241 | ResponseBody     | Messages consumed from topic   | Json       | Json         |                                                           |
 242 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 243
 244
 245 Response /Error Codes
 246 =====================
 247
 248
 249 +---------------------------+------------------------------------+
 250 | Response statusCode       | Response statusMessage             |
 251 +===========================+====================================+
 252 | 200-299                   | Success                            |
 253 +---------------------------+------------------------------------+
 254 | 400-499                   | the client request has a problem   |
 255 +---------------------------+------------------------------------+
 256 | 500-599                   | the DMaaP service has a problem    |
 257 +---------------------------+------------------------------------+
 258
 259 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
 260 | Error code              |  HTTPCode       |  Description               | Issue Reason                                                                                |
 261 +=========================+=================+============================+=============================================================================================+
 262 | DMaaP\_MR\_ERR\_3008    | 413             | Request Entity too large   | Message size exceeds the batch limit <limit>.Reduce the batch size and try again            |
 263 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
 264 | DMaaP\_MR\_ERR\_3009    | 500             | Internal Server Error      | Unable to publish messages. Please contact administrator                                    |
 265 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
 266 | DMaaP\_MR\_ERR\_3010    | 400             | Bad Request                | Incorrect Batching format. Please correct the batching format and try again                 |
 267 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
 268 | DMaaP\_MR\_ERR\_3011    | 413             | Request Entity too large   | Message size exceeds the message size limit <limit>.Reduce the message size and try again   |
 269 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
 270 | DMaaP\_MR\_ERR\_5012    | 429             | Too many requests          | This client is making too many requests. Please use a long poll setting to decrease the     |
 271 |                         |                 |                            | number of requests that result in empty responses.                                          |
 272 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
 273 |                         | 503             | Service Unavailable        | Service Unavailable.                                                                        |
 274 +-------------------------+-----------------+----------------------------+---------------------------------------------------------------------------------------------+
 275
 276 Sample Request:
 277 ===============
 278
 279 +----------------------------------------------------------------------------------------------------+
 280 | GET  http://<hostname>:3904/events/com.att.dmaap.mr.sprint/mygroup/mycus                           |
 281 |                                                                                                    |
 282 | Content-Type: application/json                                                                     |
 283 |                                                                                                    |
 284 | Example:                                                                                           |
 285 |                                                                                                    |
 286 |curl -u XXX@csp.abc.com:MRDmap2016$ -X GET -d 'MyfirstMessage'                                      |
 287 |                                                                                                    |
 288 |http://mrlocal00.dcae.proto.research.att.com:3904/events/com.att.ecomp_test.crm.preDeo/myG/C1       |
 289 |                                                                                                    |
 290 |[I am r sending first msg,I am R sending first msg]                                                 |
 291 +----------------------------------------------------------------------------------------------------+
 292
 293 Provisioning
 294 ------------
 295 **Description**: To create , modify or delete the MessageRouter topics.These APIs can also be used by other applications to provision topics in MessageRouter.
 296 DMaaP BusController is recommended for topic and AAf permissions provisoning
 297
 298 Create Topic
 299 ============
 300 Request URL:
 301 ============
 302
 303 POST http(s)://{HOST:PORT}/topics/create
 304
 305 Request Parameters:
 306 ===================
 307
 308 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
 309 | Name              | Description                     |  Param Type      |  datatype  |   MaxLen     |  Required   |  Format     |  Valid/Example Values             |
 310 +===================+=================================+==================+============+==============+=============+=============+===================================+
 311 | Topicname         | topicname to be created in MR   |     Body         |   String   |     20       |     Y       | Json        | org.onap.dmaap.mr.metrics          |
 312 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
 313 | topicDescription  | description for topic           |     Body         |   String   |     15       |     Y       |             |                                   |
 314 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
 315 | partitionCount    | Kafka topic partition           |     Body         |   String   |     1        |    Y        |             |                                   |
 316 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
 317 | replicationCount  | Kafka topic replication         |     Body         |   String   |     1        |    Y        |             | 3 (Default -for 3 node Kafka )    |
 318 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
 319 | transaction       | to create transaction id for    |     Body         |  Boolean   |     1        |    N        |             | true                              |
 320 | Enabled           | each message transaction        |                  |            |              |             |             |                                   |
 321 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
 322 | Content-Type      | application/json                |     Header       |   String   |              |             |             | application/json                  |
 323 +-------------------+---------------------------------+------------------+------------+--------------+-------------+-------------+-----------------------------------+
 324
 325 **NOTE**:To Create a authenticated topic, user must have the AAF permission
 326  org.onap.dmaap.mr.topicFactory|:org.onap.dmaap.mr.topic:org.onap.dmaap.mr|create
 327
 328
 329 +---------------------------+------------------------------------+
 330 | Response statusCode       | Response statusMessage             |
 331 +===========================+====================================+
 332 | 200-299                   | Success                            |
 333 +---------------------------+------------------------------------+
 334 | 400-499                   | the client request has a problem   |
 335 +---------------------------+------------------------------------+
 336 | 500-599                   | the DMaaP service has a problem    |
 337 +---------------------------+------------------------------------+
 338
 339
 340 +-------------------------+-----------------+--------------------------------------------------+
 341 | Error code              |  HTTP Code      |  Description                                     |
 342 +=========================+=================+==================================================+
 343 | DMaaP\_MR\_ERR\_5001    | 500             | Failed to retrieve list of all topics            |
 344 +-------------------------+-----------------+--------------------------------------------------+
 345 | DMaaP\_MR\_ERR\_5002    | 500             | Failed to retrieve details of topic:<topicName>  |
 346 +-------------------------+-----------------+--------------------------------------------------+
 347 | DMaaP\_MR\_ERR\_5003    | 500             | Failed to create topic:<topicName>               |
 348 +-------------------------+-----------------+--------------------------------------------------+
 349 | DMaaP\_MR\_ERR\_5004    | 500             | Failed to delete topic:<topicName>               |
 350 +-------------------------+-----------------+--------------------------------------------------+
 351
 352
 353 Response Parameters
 354 ====================
 355
 356 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 357 | Name             | Description                    |  Type      | Format       | Valid/Example Values                                      |
 358 +==================+================================+============+==============+===========================================================+
 359 | httpStatusCode   |                                |            |              | 200, 201 etc.                                             |
 360 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 361 | mrErrorCode      | Numeric error code             |            |              | 5005                                                      |
 362 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 363 | errorMessage     |                                |            |              | SUCCESS, or error message.                                |
 364 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 365 | helpURL          | helpurl                        |            |              |                                                           |
 366 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 367 | ResponseBody     | Topic details (owner,          |  Json      |  Json        |                                                           |
 368 |                  | trxEnabled=true)               |            |              |                                                           |
 369 +------------------+--------------------------------+------------+--------------+-----------------------------------------------------------+
 370
 371
 372 Sample Request:
 373 ===============
 374
 375     .. code:: bash
 376
 377       POST   http://<hostname>:3904/topic/create
 378   Request Body
 379   {"topicName":"org.onap.dmaap.mr.testtopic","description":"This is a test Topic ",
 380   "partitionCount":"1","replicationCount":"3","transactionEnabled":"true"}
 381   Content-Type: application/json
 382   Example:
 383   curl -u XXXc@csp.abc.com:xxxxx$  -H 'Content-Type:application/json' -X POST -d
 384   @topicname.txt  http://message-router:3904/topics/create
 385   {
 386   "writerAcl": {
 387   "enabled": false,
 388   "users": []
 389   },
 390   "description": "This is a TestTopic",
 391   "name": "org.onap.dmaap.mr.testtopic",
 392   "readerAcl": {
 393   "enabled": false,
 394   "users": []
 395
 396
 397 GetTopic Details
 398 ----------------
 399
 400 Request URL
 401 ===========
 402
 403 GET http(s)://{HOST:PORT}/topics    : To list the details of all the topics in Message Router.
 404
 405 GET http(s)://{HOST:PORT}/topics/{topicname} : To list the details of specified topic .
 406
 407 Request Parameters
 408 ==================
 409
 410 +--------------------------+-------------------------+------------------+------------+-----------+-------------+-----------------+-----------------------------+
 411 | Name                     | Description             | Param Type       | Data type  | Max Len   | Required    | Format          | Valid/EXample values        |
 412 +==========================+=========================+==================+============+===========+=============+=================+=============================+
 413 | Topicname                | topic name details      | Body             | String     | 20        | Y           |  Json           | org.onap.dmaap.mr.testtopic |
 414 +--------------------------+-------------------------+------------------+------------+-----------+-------------+-----------------+-----------------------------+
 415
 416 **NOTE**:To view a authenticated topic, user must have the AAF permission
 417  org.onap.dmaap.mr.topic|*|view
 418
 419
 420 Response Parameters
 421 ====================
 422
 423 +------------------+------------------------+------------+----------+---------+----------------------------+
 424 | Name             | Description            | ParamType  | datatype |Format   | Valid/Example Values       |
 425 +==================+========================+============+==========+=========+============================+
 426 | topicname        |  topic name details    |      Body  |   String |   Json  | org.onap.dmaap.mr.testopic |
 427 +------------------+------------------------+------------+----------+---------+----------------------------+
 428 | description      |                        |            |   String |         |                            |
 429 +------------------+------------------------+------------+----------+---------+----------------------------+
 430 | owner            |user id who created the |            |          |         |                            |
 431 |                  |         topic          |            |          |         |                            |
 432 +------------------+------------------------+------------+----------+---------+----------------------------+
 433 | txenabled        |     true or false      |            |  boolean |         |                            |
 434 +------------------+------------------------+------------+----------+---------+----------------------------+
 435
 436 +---------------------------+------------------------------------+
 437 | Response statusCode       | Response statusMessage             |
 438 +===========================+====================================+
 439 | 200-299                   | Success                            |
 440 +---------------------------+------------------------------------+
 441 | 400-499                   | the client request has a problem   |
 442 +---------------------------+------------------------------------+
 443 | 500-599                   | the DMaaP service has a problem    |
 444 +---------------------------+------------------------------------+
 445
 446
 447 Sample Request:
 448 ===============
 449
 450 +-----------------------------------------------------------------------------------------------------------------------------------+
 451 | GET   http://<hostname>:3904/topic/com.att.dmaap.mr.testtopic                                                                     |
 452 |       curl -u XXX@csp.abc.com:x$  -X                                                                                              |
 453 | GET  http://mrlocal00.dcae.proto.research.att.com:3904/topics                                                                     |
 454 |    {"topics": [                                                                                                                   |
 455 |    {"txenabled": true,"description": "This is a TestTopic","owner": "XXXX@csp.abc.com","topicName": "org.onap.dmaap.mr.Load9"|
 456 |    {"txenabled": false,"description": "", "owner": "", "topicName": "org.onap.dmaap.mr.Load1"                                |
 457 |    ]},                                                                                                                            |
 458 +-----------------------------------------------------------------------------------------------------------------------------------+
 459
 460
 461 Delete Topics
 462 -------------
 463
 464 Request URL:
 465 ============
 466
 467 DELETE http(s)://{HOST:PORT}/topic/{topicname}
 468
 469 **NOTE**:To delete a  topic, user must have the AAF permission
 470 org.onap.dmaap.mr.topicFactory|:org.onap.dmaap.mr.topic:org.onap.dmaap.mr|destroy
 471
 472 Sample Request:
 473 ===============
 474 ex: http://<hostname>:3904/dmaap/v1/topics/org.onap.dmaap.mr.testopic
 475
 476 +---------------------------+------------------------------------+
 477 | Response statusCode       | Response statusMessage             |
 478 +===========================+====================================+
 479 | 200-299                   | Success                            |
 480 +---------------------------+------------------------------------+
 481 | 400-499                   | the client request has a problem   |
 482 +---------------------------+------------------------------------+
 483 | 500-599                   | the DMaaP service has a problem    |
 484 +---------------------------+------------------------------------+
 485
 486 +-------------------------+---------------------------------------------+----------------------+
 487 | Error code              |    Description                              |HTTP code             |
 488 +=========================+=============================================+======================+
 489 |  DMaaP\_MR\_ERR\_5004   |  Failed to delete topic:<topicName>         |   500                |
 490 +-------------------------+---------------------------------------------+----------------------+
 491
 492 API Inventory
 493 -------------
 494
 495 +-----------+--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
 496 |           |   API Name         |   API Method                            |   REST API Path                       |                | Comments                         |
 497 +===========+====================+=========================================+=======================================+================+==================================+
 498 | Topics    | GetAll Topics      | getTopics()                             | /topics                               | GET            |                                  |
 499 |           | List               |                                         |                                       |                |                                  |
 500 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
 501 |           | Get All Topics     |                                         |                                       |                |                                  |
 502 |           | List with details  | getAllTopics()                          | /topics/listAll                       | GET            |                                  |
 503 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
 504 |           | Get individual     |                                         |                                       |                |                                  |
 505 |           | Topic Details      | getTopic(String topicName)              | /topics/{topicName}                   | GET            |                                  |
 506 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
 507 |           | Create Topic       | createTopic(TopicBean topicBean)        | /topics/create                        | POST           |                                  |
 508 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
 509 |           | Delete Topic       | deleteTopicString topicName)            | /topics/{topicName}                   | DELETE         |  Not used in current MR version  |
 510 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
 511 |           | Get Publishers     | getPublishersByTopicName                |                                       |                |                                  |
 512 |           | for a Topic        | String topicName)                       | /topics/{topicName}/producers         | GET            |  UEB Backward Compatibility      |
 513 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+                                  |
 514 |           | Add a Publisher    | permitPublisherForTopic                 | /topics/{topicName}/producers/        | PUT            |                                  |
 515 |           | to write ACLon     | (String topicName, String producerId)   | {producerId}                          |                |                                  |
 516 |           | a Topic            |                                         |                                       |                |                                  |
 517 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+                                  |
 518 |           | Remove a Publisher | denyPublisherForTopic(String topicName, | /topics/{topicName}/producers/        | DELETE         |                                  |
 519 |           | from write ACL on  | String producerId)                      | {producerId}                          |                |                                  |
 520 |           | a Topic            |                                         |                                       |                |                                  |
 521 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+                                  |
 522 |           | Get Consumers for  | getConsumersByTopicName                 | /topics/{topicName}/consumers         |  GET           |                                  |
 523 |           | a Topic            | (String topicName)                      |                                       |                |                                  |
 524 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+                                  |
 525 |           | Add a Consumer     | permitConsumerForTopic(String           | /topics/{topicName}/consumers/        |  PUT           |                                  |
 526 |           | to read ACL        | topicName,String consumerId)            | {consumerId}                          |                |                                  |
 527 |           | on a Topic         |                                         |                                       |                |                                  |
 528 |           +--------------------+-----------------------------------------+---------------------------------------+----------------+                                  |
 529 |           | Remove a consumer  | denyPublisherForTopic(String topicName, | /topics/{topicName}/consumers/        | DELETE         |                                  |
 530 |           | from write         | String consumerId)                      | {consumerId}                          |                |                                  |
 531 |           | ACL on a Topic     |                                         |                                       |                |                                  |
 532 +-----------+--------------------+-----------------------------------------+---------------------------------------+----------------+----------------------------------+
 533
 534
 535