docs/offered-apis.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.\r
   2 .. http://creativecommons.org/licenses/by/4.0\r
   3 \r
   4 .. _data_router_api_guide:\r
   5 \r
   6 .. toctree::\r
   7    :maxdepth: 2\r
   8 \r
   9 Offered APIs\r
  10 ============\r
  11 \r
  12 **The API Provisioning Model**\r
  13 \r
  14 The DMaaP Data Router (DR) provisioning API defines two resource types - the feed and the subscription, each with JSON\r
  15 representations. The API models the provisioning data as a collection of feeds that are known to the DR\r
  16 (the feeds collection), with each feed containing a collection of the subscriptions to the feed.\r
  17 The standard HTTP operations (POST, GET, PUT, and DELETE), used in conjunction with these resource\r
  18 representations, allow an API user to create, get information about, modify, and delete feeds and\r
  19 subscriptions.\r
  20 \r
  21 **HTTP Service APIs**\r
  22 \r
  23 DMaaP Data Router utilizes an HTTPS REST API to service all transactions. HTTPS and REST standards are followed so\r
  24 clients as varied as CURL, Java applications and even Web Browsers will work to interact with the Data Router.\r
  25 \r
  26 **General HTTP Requirements**\r
  27 \r
  28 A DMaaP Data Router transactions consists of 4 distinct segments, HTTP URL, HTTP Header, HTTP Body (POST/PUT)\r
  29 and HTTP Response. The general considerations for each segment are as follows and are required for each\r
  30 of the specific transactions described in this section.\r
  31 \r
  32 **HTTP URL**\r
  33 \r
  34 http[s]://{serverBaseURL}/{resourcePath}\r
  35 \r
  36 * The serverBaseURL points to DMaaP Data Router host:port that will service the request.\r
  37 * The resourcePath specifies the service that the client is attempting to reach.\r
  38 \r
  39 \r
  40 **HTTP Header**\r
  41 \r
  42 Specifies HTTP Headers, such as Content-Type, that define the parameters of the HTTP Transaction\r
  43 \r
  44 **HTTP Body**\r
  45 \r
  46 The HTTP Body contains the feed content when creating a feed.\r
  47 \r
  48 **HTTP Authorization**\r
  49 \r
  50 The user-id:password pair:\r
  51 \r
  52 * If AAF enabled:  A valid AAF AppId to be authenticated and authorized by the AAF CADI framework.\r
  53 * If Non AAF    :  When publishing or retracting a file, a valid `EID Object`_ with publish permissions.\r
  54 \r
  55 Create a Feed\r
  56 -------------\r
  57 \r
  58 **Description**: Creates a unique feed URL to service the publisher/subscriber model.\r
  59 \r
  60 .. code-block:: bash\r
  61 \r
  62     POST /\r
  63 \r
  64 **Request Parameters:**\r
  65 \r
  66 +----------------------+--------------------------------+------------+------------------+--------+--------+------------+----------+-------------------------------+\r
  67 | Field                | Description                    | Param Type | Data Type        | MaxLen | Set By | Updatable? | Required |  Valid/Example Values         |\r
  68 +======================+================================+============+==================+========+========+============+==========+===============================+\r
  69 | name                 | Feed name                      | Body       | String           | <=20   | Client | N          | Y        |                               |\r
  70 +----------------------+--------------------------------+------------+------------------+--------+--------+------------+----------+-------------------------------+\r
  71 | version              | Feed version                   | Body       | String           | <=20   | Client | N          | Y        | v1.0.0                        |\r
  72 +----------------------+--------------------------------+------------+------------------+--------+--------+------------+----------+-------------------------------+\r
  73 | description          | Feed description               | Body       | String           | <=256  | Client | Y          | N        |                               |\r
  74 +----------------------+--------------------------------+------------+------------------+--------+--------+------------+----------+-------------------------------+\r
  75 | business description | Business description           | Body       | String           | <=256  | Client | Y          | N        |                               |\r
  76 +----------------------+--------------------------------+------------+------------------+--------+--------+------------+----------+-------------------------------+\r
  77 | authorization        | Information for authorizing    | Body       |`Auth Object`_    |        | Client | Y          | Y        |                               |\r
  78 |                      | publishing requests            |            |                  |        |        |            |          |                               |\r
  79 +----------------------+--------------------------------+------------+------------------+--------+--------+------------+----------+-------------------------------+\r
  80 | suspend              | Set to true if the feed is in  | Body       | Boolean          |        | Client | Y          | N        | * true                        |\r
  81 |                      | the suspended state            |            |                  |        |        |            |          | * false (default)             |\r
  82 +----------------------+--------------------------------+------------+------------------+--------+--------+------------+----------+-------------------------------+\r
  83 | group-id             | Auth group for feed management | Body       | Integer          |        | Client | Y          | N        | 0 (default)                   |\r
  84 +----------------------+--------------------------------+------------+------------------+--------+--------+------------+----------+-------------------------------+\r
  85 | aaf_instance         | The instance passed to aaf     | Body       | String           | <=256  | Client | N          | N        | legacy (default)              |\r
  86 |                      | during permission checks       |            |                  |        |        |            |          |                               |\r
  87 +----------------------+--------------------------------+------------+------------------+--------+--------+------------+----------+-------------------------------+\r
  88 | Content-Type         | To specify type of message     | Header     | String           |        | Client | N          | Y        | application/vnd.dmaap-dr.feed |\r
  89 +----------------------+--------------------------------+------------+------------------+--------+--------+------------+----------+-------------------------------+\r
  90 | publisher            | Publisher identity as passed   | Header     | String           | <=8    | DR     | N          | Y        | username                      |\r
  91 |                      | in X-DMAAP-DR-ON-BEHALF-OF at  |            |                  |        |        |            |          |                               |\r
  92 |                      | creation time                  |            |                  |        |        |            |          |                               |\r
  93 +----------------------+--------------------------------+------------+------------------+--------+--------+------------+----------+-------------------------------+\r
  94 | Authorization        | The user / AppId to be         | Header     | String           |        | Client | N          | Y if AAF | dcae@dcae.onap.org:{password} |\r
  95 |                      | authorized by the AAF CADI     |            |                  |        |        |            | enabled  |                               |\r
  96 |                      | framework                      |            |                  |        |        |            |          |                               |\r
  97 +----------------------+--------------------------------+------------+------------------+--------+--------+------------+----------+-------------------------------+\r
  98 | X-EXCLUDE-AAF        | To determine if the feed to    | Header     | Boolean          |        | Client | N          | Y if AAF | * true (for legacy feed)      |\r
  99 |                      | create is legacy or AAF        |            |                  |        |        |            | enabled  | * false (for AAF feed)        |\r
 100 +----------------------+--------------------------------+------------+------------------+--------+--------+------------+----------+-------------------------------+\r
 101 | Links                | URLs related to this feed      | Body       |`Feed Links Obj`_ |        | DR     | N          | N        |                               |\r
 102 +----------------------+--------------------------------+------------+------------------+--------+--------+------------+----------+-------------------------------+\r
 103 \r
 104 **Response Codes**\r
 105 \r
 106 * Success:\r
 107     200\r
 108 \r
 109 * Error:\r
 110     See `Response Codes`_\r
 111 \r
 112 **Consumes**\r
 113     application/json\r
 114 \r
 115 **Produces**\r
 116     application/json\r
 117 \r
 118 \r
 119 **Sample Request**\r
 120 \r
 121 .. code-block:: bash\r
 122 \r
 123     curl -k -X POST -H "Content-Type:application/vnd.dmaap-dr.feed" -H "X-DMAAP-DR-ON-BEHALF-OF:{user}" --data-ascii @createFeed.json https://{host}:{port}\r
 124 \r
 125 **Sample Body**\r
 126 \r
 127 .. code-block:: json\r
 128 \r
 129     {\r
 130       "name": "ONAP Data Feed",\r
 131       "version": "v1.0",\r
 132       "authorization": {\r
 133         "classification": "unclassified",\r
 134         "endpoint_addrs": [\r
 135         ],\r
 136         "endpoint_ids": [\r
 137           {\r
 138             "id": "dradmin",\r
 139             "password": "dradmin"\r
 140           }\r
 141         ]\r
 142       }\r
 143     }\r
 144 \r
 145 **Sample Response**\r
 146 \r
 147 .. code-block:: json\r
 148 \r
 149     {\r
 150       "suspend": false,\r
 151       "groupid": 0,\r
 152       "description": "",\r
 153       "version": "v1.0",\r
 154       "authorization": {\r
 155         "endpoint_addrs": [\r
 156         ],\r
 157         "classification": "unclassified",\r
 158         "endpoint_ids": [\r
 159           {\r
 160             "password": "dradmin",\r
 161             "id": "dradmin"\r
 162           },\r
 163           {\r
 164             "password": "demo123456!",\r
 165             "id": "onap"\r
 166           }\r
 167         ]\r
 168       },\r
 169       "name": "ONAP Data Feed",\r
 170       "business_description": "",\r
 171       "aaf_instance": "legacy",\r
 172       "publisher": "dradmin",\r
 173       "links": {\r
 174         "subscribe": "https://dmaap-dr-prov/subscribe/1",\r
 175         "log": "https://dmaap-dr-prov/feedlog/1",\r
 176         "publish": "https://dmaap-dr-prov/publish/1",\r
 177         "self": "https://dmaap-dr-prov/feed/1"\r
 178       }\r
 179     }\r
 180 \r
 181 \r
 182 \r
 183 Update a Feed\r
 184 -------------\r
 185 \r
 186 **Description**: Update a feed with new parameters.\r
 187 \r
 188 .. code-block:: bash\r
 189 \r
 190     PUT /feed/{feedId}\r
 191 \r
 192 \r
 193 **Request Parameters:**\r
 194 \r
 195 +------------------------+---------------------------------+-------------+---------------+------------+-------------+\r
 196 | Field                  | Description                     |  Param Type |  Data Type    |  MaxLen    |  Required   |\r
 197 +========================+=================================+=============+===============+============+=============+\r
 198 | name                   | Feed name                       |     Body    |   String      |   <=20     |     Y       |\r
 199 +------------------------+---------------------------------+-------------+---------------+------------+-------------+\r
 200 | description            | Feed description                |     Body    |   String      |   <=256    |     N       |\r
 201 +------------------------+---------------------------------+-------------+---------------+------------+-------------+\r
 202 | business description   | Business description            |     Body    |   String      |   <=256    |     N       |\r
 203 +------------------------+---------------------------------+-------------+---------------+------------+-------------+\r
 204 | authorization          | Information for authorizing     |     Body    |`Auth Object`_ |            |     Y       |\r
 205 |                        | publishing requests             |             |               |            |             |\r
 206 +------------------------+---------------------------------+-------------+---------------+------------+-------------+\r
 207 | suspend                | Set to true if the feed is in   |     Body    |   Boolean     |            |     N       |\r
 208 |                        | the suspended state             |             |               |            |             |\r
 209 +------------------------+---------------------------------+-------------+---------------+------------+-------------+\r
 210 | group-id               | Auth group for feed management  |     Body    |   Integer     |            |     N       |\r
 211 |                        |                                 |             |               |            |             |\r
 212 +------------------------+---------------------------------+-------------+---------------+------------+-------------+\r
 213 | Content-type           | To specify type of message      |    Header   |   String      |            |     Y       |\r
 214 |                        | (feed,subscriber,publisher)     |             |               |            |             |\r
 215 +------------------------+---------------------------------+-------------+---------------+------------+-------------+\r
 216 | publisher              | Publisher identity as passed    |    Header   |   String      |   <=8      |     Y       |\r
 217 |                        | in X-DMAAP-DR-ON-BEHALF-OF at   |             |               |            |             |\r
 218 |                        | creation time                   |             |               |            |             |\r
 219 +------------------------+---------------------------------+-------------+---------------+------------+-------------+\r
 220 | Authorization          | The user / AppId to be          |    Header   |   String      |            | Y if AAF    |\r
 221 |                        | authorized by the AAF CADI      |             |               |            | enabled     |\r
 222 |                        | framework                       |             |               |            |             |\r
 223 +------------------------+---------------------------------+-------------+---------------+------------+-------------+\r
 224 \r
 225 **Response Codes**\r
 226 \r
 227 * Success:\r
 228     200\r
 229 \r
 230 * Error:\r
 231     See `Response Codes`_\r
 232 \r
 233 **Consumes**\r
 234     application/json\r
 235 \r
 236 **Produces**\r
 237     application/json\r
 238 \r
 239 \r
 240 **Sample Request**\r
 241 \r
 242 .. code-block:: bash\r
 243 \r
 244     curl -k -X PUT -H "Content-Type: application/vnd.dmaap-dr.feed" -H "X-DMAAP-DR-ON-BEHALF-OF: {user}" --data-ascii @updateFeed.json --location-trusted https://{host}:{port}/feed/{feedId}\r
 245 \r
 246 **Sample Body**\r
 247 \r
 248 .. code-block:: json\r
 249 \r
 250     {\r
 251       "name": "ONAP Data Feed",\r
 252       "business_description": "Updated ONAP Feed",\r
 253       "groupid": 33,\r
 254       "description": "Updated ONAP Feed",\r
 255       "authorization": {\r
 256         "endpoint_addrs": [\r
 257           "10.1.2.3"\r
 258         ],\r
 259         "classification": "unclassified",\r
 260         "endpoint_ids": [\r
 261           {\r
 262             "password": "dradmin",\r
 263             "id": "dradmin"\r
 264           },\r
 265           {\r
 266             "password": "demo123456!",\r
 267             "id": "onap"\r
 268           }\r
 269         ]\r
 270       }\r
 271     }\r
 272 \r
 273 **Sample Response**\r
 274 \r
 275 .. code-block:: json\r
 276 \r
 277     {\r
 278       "suspend": false,\r
 279       "groupid": 33,\r
 280       "description": "Updated ONAP Feed",\r
 281       "authorization": {\r
 282         "endpoint_addrs": [\r
 283           "10.1.2.3"\r
 284         ],\r
 285         "classification": "unclassified",\r
 286         "endpoint_ids": [\r
 287           {\r
 288             "password": "dradmin",\r
 289             "id": "dradmin"\r
 290           },\r
 291           {\r
 292             "password": "demo123456!",\r
 293             "id": "onap"\r
 294           }\r
 295         ]\r
 296       },\r
 297       "name": "ONAP Data Feed1",\r
 298       "business_description": "Updated ONAP Feed",\r
 299       "aaf_instance": "legacy",\r
 300       "publisher": "dradmin",\r
 301       "links": {\r
 302         "subscribe": "https://dmaap-dr-prov/subscribe/1",\r
 303         "log": "https://dmaap-dr-prov/feedlog/1",\r
 304         "publish": "https://dmaap-dr-prov/publish/1",\r
 305         "self": "https://dmaap-dr-prov/feed/1"\r
 306       }\r
 307     }\r
 308 \r
 309 \r
 310 \r
 311 Get a Feed\r
 312 ----------\r
 313 \r
 314 **Description**: Retrieves a representation of the specified feed.\r
 315 \r
 316 .. code-block:: bash\r
 317 \r
 318     GET /feed/{feedId}\r
 319 \r
 320 \r
 321 **Request Parameters:**\r
 322 \r
 323 +------------------------+---------------------------------+-------------+---------------+------------+-------------+\r
 324 | Field                  | Description                     |  Param Type |  Data Type    |  MaxLen    |  Required   |\r
 325 +========================+=================================+=============+===============+============+=============+\r
 326 | publisher              | Publisher identity as passed    |    Header   |   String      |   <=8      |     Y       |\r
 327 |                        | in X-DMAAP-DR-ON-BEHALF-OF at   |             |               |            |             |\r
 328 |                        | creation time                   |             |               |            |             |\r
 329 +------------------------+---------------------------------+-------------+---------------+------------+-------------+\r
 330 | Authorization          | The user / AppId to be          |    Header   |   String      |            | Y if AAF    |\r
 331 |                        | authorized by the AAF CADI      |             |               |            | enabled     |\r
 332 |                        | framework                       |             |               |            |             |\r
 333 +------------------------+---------------------------------+-------------+---------------+------------+-------------+\r
 334 \r
 335 **Response Codes**\r
 336 \r
 337 * Success:\r
 338     200\r
 339 \r
 340 * Error:\r
 341     See `Response Codes`_\r
 342 \r
 343 **Produces**\r
 344     application/json\r
 345 \r
 346 **Sample Request**\r
 347 \r
 348 .. code-block:: bash\r
 349 \r
 350     curl -k -H "X-DMAAP-DR-ON-BEHALF-OF: {user}" https://{host}:{port}/feed/{feedId}\r
 351 \r
 352 **Sample Response**\r
 353 \r
 354 .. code-block:: json\r
 355 \r
 356     {\r
 357       "suspend": false,\r
 358       "groupid": 33,\r
 359       "description": "Updated ONAP Feed",\r
 360       "version": "v1.0",\r
 361       "authorization": {\r
 362         "endpoint_addrs": [\r
 363           "10.1.2.3",\r
 364           "173.2.33.4"\r
 365         ],\r
 366         "classification": "unclassified",\r
 367         "endpoint_ids": [\r
 368           {\r
 369             "password": "dradmin",\r
 370             "id": "dradmin"\r
 371           },\r
 372           {\r
 373             "password": "demo123456!",\r
 374             "id": "onap"\r
 375           }\r
 376         ]\r
 377       },\r
 378       "name": "ONAP Data Feed",\r
 379       "business_description": "Updated ONAP Feed",\r
 380       "aaf_instance": "legacy",\r
 381       "publisher": "dradmin",\r
 382       "links": {\r
 383         "subscribe": "https://dmaap-dr-prov/subscribe/1",\r
 384         "log": "https://dmaap-dr-prov/feedlog/1",\r
 385         "publish": "https://dmaap-dr-prov/publish/1",\r
 386         "self": "https://dmaap-dr-prov/feed/1"\r
 387       }\r
 388     }\r
 389 \r
 390 \r
 391 Delete a Feed\r
 392 -------------\r
 393 \r
 394 **Description**: Deletes a specified feed\r
 395 \r
 396 .. code-block:: bash\r
 397 \r
 398     DELETE /feed/{feedId}\r
 399 \r
 400 \r
 401 **Request Parameters:**\r
 402 \r
 403 +------------------------+---------------------------------+-------------+---------------+------------+-------------+\r
 404 | Field                  | Description                     |  Param Type |  Data Type    |  MaxLen    |  Required   |\r
 405 +========================+=================================+=============+===============+============+=============+\r
 406 | publisher              | Publisher identity as passed    |    Header   |   String      |   <=8      |     Y       |\r
 407 |                        | in X-DMAAP-DR-ON-BEHALF-OF at   |             |               |            |             |\r
 408 |                        | creation time                   |             |               |            |             |\r
 409 +------------------------+---------------------------------+-------------+---------------+------------+-------------+\r
 410 | Authorization          | The user / AppId to be          |    Header   |   String      |            | Y if AAF    |\r
 411 |                        | authorized by the AAF CADI      |             |               |            | enabled     |\r
 412 |                        | framework                       |             |               |            |             |\r
 413 +------------------------+---------------------------------+-------------+---------------+------------+-------------+\r
 414 \r
 415 **Response Codes**\r
 416 \r
 417 * Success:\r
 418     204\r
 419 \r
 420 * Error:\r
 421     See `Response Codes`_\r
 422 \r
 423 **Sample Request**\r
 424 \r
 425 .. code-block:: bash\r
 426 \r
 427     curl -k -X DELETE -H "X-DMAAP-DR-ON-BEHALF-OF: {user}" https://{host}:{port}/feed/{feedId}\r
 428 \r
 429 \r
 430 Subscribe to Feed\r
 431 -----------------\r
 432 \r
 433 **Description**: Subscribes to a created feed to receive files published to that feed.\r
 434 \r
 435 .. code-block:: bash\r
 436 \r
 437     POST /subscribe/{feedId}\r
 438 \r
 439 \r
 440 **Request Parameters:**\r
 441 \r
 442 +-----------------+---------------------------------+---------------+-----------------+--------+--------+------------+----------+--------------------------------------+\r
 443 | Field           | Description                     |  Param Type   |  Data Type      | MaxLen | Set By | Updatable? | Required |  Valid/Example Values                |\r
 444 +=================+=================================+===============+=================+========+========+============+==========+======================================+\r
 445 | feedId          | ID for the feed you are         |     Path      |   String        |        | Client |     N      |     Y    | 1                                    |\r
 446 |                 | subscribing to                  |               |                 |        |        |            |          |                                      |\r
 447 +-----------------+---------------------------------+---------------+-----------------+--------+--------+------------+----------+--------------------------------------+\r
 448 | delivery        | Address and credentials for     |     Body      | `Del Object`_   |        | Client |     Y      |     Y    |                                      |\r
 449 |                 | delivery                        |               |                 |        |        |            |          |                                      |\r
 450 +-----------------+---------------------------------+---------------+-----------------+--------+--------+------------+----------+--------------------------------------+\r
 451 | follow_redirect | Set to true if feed redirection |     Body      |   Boolean       |        | Client |     Y      |     N    | * true                               |\r
 452 |                 | is expected                     |               |                 |        |        |            |          | * false (default)                    |\r
 453 +-----------------+---------------------------------+---------------+-----------------+--------+--------+------------+----------+--------------------------------------+\r
 454 | metadata_only   | Set to true if subscription is  |     Body      |   Boolean       |        | Client |     Y      |     Y    | * true                               |\r
 455 |                 | to receive per-file metadata    |               |                 |        |        |            |          | * false                              |\r
 456 +-----------------+---------------------------------+---------------+-----------------+--------+--------+------------+----------+--------------------------------------+\r
 457 | suspend         | Set to true if the subscription |     Body      |   Boolean       |        | Client |     Y      |     N    | * true                               |\r
 458 |                 | is in the suspended state       |               |                 |        |        |            |          | * false (default)                    |\r
 459 +-----------------+---------------------------------+---------------+-----------------+--------+--------+------------+----------+--------------------------------------+\r
 460 | decompress      | Set to true if the data is to   |     Body      |   Boolean       |        | Client |     Y      |     N    | * true                               |\r
 461 |                 | be decompressed for subscriber  |               |                 |        |        |            |          | * false (default)                    |\r
 462 +-----------------+---------------------------------+---------------+-----------------+--------+--------+------------+----------+--------------------------------------+\r
 463 | group-id        | Auth group for sub management   |     Body      |   Integer       |        | Client |     Y      |     Y    | 22                                   |\r
 464 |                 |                                 |               |                 |        |        |            |          |                                      |\r
 465 +-----------------+---------------------------------+---------------+-----------------+--------+--------+------------+----------+--------------------------------------+\r
 466 | aaf_instance    | The instance passed to aaf      |     Body      |   String        | <=256  | Client |     N      |     N    | * legacy (default)                   |\r
 467 |                 | during permission checks        |               |                 |        |        |            |          |                                      |\r
 468 |                 |                                 |               |                 |        |        |            |          |                                      |\r
 469 +-----------------+---------------------------------+---------------+-----------------+--------+--------+------------+----------+--------------------------------------+\r
 470 | Content-type    | To specify type of message      |     Header    |   String        |        | Client |     N      |     Y    | application/vnd.dmaap-dr.subscription|\r
 471 |                 | (feed,subscriber,publisher)     |               |                 |        |        |            |          |                                      |\r
 472 +-----------------+---------------------------------+---------------+-----------------+--------+--------+------------+----------+--------------------------------------+\r
 473 | subscriber      | Subscriber identity as passed   |     Header    |   String        |   <=8  |  DR    |     N      |     Y    | username                             |\r
 474 |                 | in X-DMAAP-DR-ON-BEHALF-OF at   |               |                 |        |        |            |          |                                      |\r
 475 |                 | creation time                   |               |                 |        |        |            |          |                                      |\r
 476 +-----------------+---------------------------------+---------------+-----------------+--------+--------+------------+----------+--------------------------------------+\r
 477 | Authorization   | The user / AppId to be          |    Header     |   String        |        | Client |     N      | Y if AAF | dcae@dcae.onap.org:{password}        |\r
 478 |                 | authorized by the AAF CADI      |               |                 |        |        |            | enabled  |                                      |\r
 479 |                 | framework                       |               |                 |        |        |            |          |                                      |\r
 480 +-----------------+---------------------------------+---------------+-----------------+--------+--------+------------+----------+--------------------------------------+\r
 481 | X-EXCLUDE-AAF   | To determine if the feed to     |    Header     |   Boolean       |        | Client |     N      | Y if AAF | * true (for legacy feed)             |\r
 482 |                 | create is legacy or AAF         |               |                 |        |        |            | enabled  | * false (for AAF feed)               |\r
 483 +-----------------+---------------------------------+---------------+-----------------+--------+--------+------------+----------+--------------------------------------+\r
 484 | Links           | URLs related to this            |     Body      |`Sub Links Obj`_ |        |  DR    |     N      |     N    |                                      |\r
 485 |                 | subscription                    |               |                 |        |        |            |          |                                      |\r
 486 +-----------------+---------------------------------+---------------+-----------------+--------+--------+------------+----------+--------------------------------------+\r
 487 \r
 488 **Response Codes**\r
 489 \r
 490 * Success:\r
 491     201\r
 492 \r
 493 * Error:\r
 494     See `Response Codes`_\r
 495 \r
 496 **Consumes**\r
 497     application/json\r
 498 \r
 499 **Produces**\r
 500     application/json\r
 501 \r
 502 \r
 503 **Sample Request**\r
 504 \r
 505 .. code-block:: bash\r
 506 \r
 507     curl -k -X POST -H "Content-Type:application/vnd.dmaap-dr.subscription" -H "X-DMAAP-DR-ON-BEHALF-OF:{user}" --data-ascii @addSubscriber.json https://{host}:{port}/subscribe/{feedId}\r
 508 \r
 509 **Sample Body**\r
 510 \r
 511 .. code-block:: json\r
 512 \r
 513     {\r
 514       "delivery": {\r
 515         "url": "http://dmaap-dr-subscriber:7070/",\r
 516         "user": "LOGIN",\r
 517         "password": "PASSWORD",\r
 518         "use100": true\r
 519       },\r
 520       "metadataOnly": false,\r
 521       "groupid": 22,\r
 522       "follow_redirect": true,\r
 523       "suspend": false,\r
 524       "decompress": true\r
 525     }\r
 526 \r
 527 **Sample Response**\r
 528 \r
 529 .. code-block:: json\r
 530 \r
 531     {\r
 532       "suspend": false,\r
 533       "delivery": {\r
 534         "use100": true,\r
 535         "password": "PASSWORD",\r
 536         "user": "LOGIN",\r
 537         "url": "http://dmaap-dr-subscriber:7070/"\r
 538       },\r
 539       "subscriber": "onap",\r
 540       "groupid": 1,\r
 541       "metadataOnly": false,\r
 542       "follow_redirect": true,\r
 543       "decompress": true,\r
 544       "aaf_instance": "legacy",\r
 545       "links": {\r
 546         "feed": "https://dmaap-dr-prov/feed/1",\r
 547         "log": "https://dmaap-dr-prov/sublog/1",\r
 548         "self": "https://dmaap-dr-prov/subs/1"\r
 549       },\r
 550       "created_date": 1553707279509\r
 551     }\r
 552 \r
 553 \r
 554 \r
 555 Update subscription\r
 556 -------------------\r
 557 \r
 558 **Description**: Update a subscription to a feed.\r
 559 \r
 560 .. code-block:: bash\r
 561 \r
 562     PUT /subs/{subId}\r
 563 \r
 564 \r
 565 **Request Parameters:**\r
 566 \r
 567 +-----------------+---------------------------------+--------------+---------------+--------+-------------+\r
 568 | Field           | Description                     |  Param Type  |  Data Type    | MaxLen |  Required   |\r
 569 +=================+=================================+==============+===============+========+=============+\r
 570 | subId           | ID for the subscription you are |     Path     |   String      |        |     Y       |\r
 571 |                 | updating                        |              |               |        |             |\r
 572 +-----------------+---------------------------------+--------------+---------------+--------+-------------+\r
 573 | delivery        | Address and credentials for     |     Body     | `Del Object`_ |        |     Y       |\r
 574 |                 | delivery                        |              |               |        |             |\r
 575 +-----------------+---------------------------------+--------------+---------------+--------+-------------+\r
 576 | follow_redirect | Set to true if feed redirection |     Body     |   Boolean     |        |     N       |\r
 577 |                 | is expected                     |              |               |        |             |\r
 578 +-----------------+---------------------------------+--------------+---------------+--------+-------------+\r
 579 | metadata_only   | Set to true if subscription is  |     Body     |   Boolean     |        |     Y       |\r
 580 |                 | to receive per-file metadata    |              |               |        |             |\r
 581 +-----------------+---------------------------------+--------------+---------------+--------+-------------+\r
 582 | suspend         | Set to true if the subscription |     Body     |   Boolean     |        |     N       |\r
 583 |                 | is in the suspended state       |              |               |        |             |\r
 584 +-----------------+---------------------------------+--------------+---------------+--------+-------------+\r
 585 | decompress      | Set to true if the data is to   |     Body     |   Boolean     |        |     N       |\r
 586 |                 | be decompressed for subscriber  |              |               |        |             |\r
 587 +-----------------+---------------------------------+--------------+---------------+--------+-------------+\r
 588 | group-id        | Auth group for sub management   |     Body     |   Integer     |        |     Y       |\r
 589 |                 |                                 |              |               |        |             |\r
 590 +-----------------+---------------------------------+--------------+---------------+--------+-------------+\r
 591 | Content-type    | To specify type of message      |     Header   |   String      |        |     Y       |\r
 592 |                 | (feed,subscriber,publisher)     |              |               |        |             |\r
 593 +-----------------+---------------------------------+--------------+---------------+--------+-------------+\r
 594 | subscriber      | Subscriber identity as passed   |     Header   |   String      |  <=8   |     Y       |\r
 595 |                 | in X-DMAAP-DR-ON-BEHALF-OF at   |              |               |        |             |\r
 596 |                 | creation time                   |              |               |        |             |\r
 597 +-----------------+---------------------------------+--------------+---------------+--------+-------------+\r
 598 | Authorization   | The user / AppId to be          |    Header    |   String      |        |  Y if AAF   |\r
 599 |                 | authorized by the AAF CADI      |              |               |        |  enabled    |\r
 600 |                 | framework                       |              |               |        |             |\r
 601 +-----------------+---------------------------------+--------------+---------------+--------+-------------+\r
 602 | X-EXCLUDE-AAF   | To determine if the feed to     |    Header    |   Boolean     |        |  Y if AAF   |\r
 603 |                 | create is legacy or AAF         |              |               |        |  enabled    |\r
 604 +-----------------+---------------------------------+--------------+---------------+--------+-------------+\r
 605 \r
 606 **Response Codes**\r
 607 \r
 608 * Success:\r
 609     200\r
 610 \r
 611 * Error:\r
 612     See `Response Codes`_\r
 613 \r
 614 **Consumes**\r
 615     application/json\r
 616 \r
 617 **Produces**\r
 618     application/json\r
 619 \r
 620 **Sample Request**\r
 621 \r
 622 .. code-block:: bash\r
 623 \r
 624     curl -k -X PUT -H "Content-Type:application/vnd.dmaap-dr.subscription" -H "X-DMAAP-DR-ON-BEHALF-OF:{user}" --data-ascii @updateSubscriber.json https://{host}:{port}/subs/{subId}\r
 625 \r
 626 **Sample Body**\r
 627 \r
 628 .. code-block:: json\r
 629 \r
 630     {\r
 631       "delivery": {\r
 632         "url": "http://dmaap-dr-subscriber:7070/",\r
 633         "user": "NEW_LOGIN",\r
 634         "password": "NEW_PASSWORD",\r
 635         "use100": false\r
 636       },\r
 637       "metadataOnly": true,\r
 638       "groupid": 67,\r
 639       "follow_redirect": false,\r
 640       "decompress": false\r
 641     }\r
 642 \r
 643 \r
 644 **Sample Response**\r
 645 \r
 646 .. code-block:: json\r
 647 \r
 648     {\r
 649       "suspend": false,\r
 650       "delivery": {\r
 651         "use100": false,\r
 652         "password": "NEW_PASSWORD",\r
 653         "user": "NEW_LOGIN",\r
 654         "url": "http://dmaap-dr-subscriber:7070/"\r
 655       },\r
 656       "subscriber": "onap",\r
 657       "groupid": 67,\r
 658       "metadataOnly": true,\r
 659       "follow_redirect": false,\r
 660       "decompress": false,\r
 661       "aaf_instance": "legacy",\r
 662       "links": {\r
 663         "feed": "https://dmaap-dr-prov/feed/1",\r
 664         "log": "https://dmaap-dr-prov/sublog/1",\r
 665         "self": "https://dmaap-dr-prov/subs/1"\r
 666       },\r
 667       "created_date": 1553714446614\r
 668     }\r
 669 \r
 670 \r
 671 \r
 672 Get a Subscription\r
 673 ------------------\r
 674 \r
 675 **Description**: Retrieves a representation of the specified subscription.\r
 676 \r
 677 .. code-block:: bash\r
 678 \r
 679     GET /subs/{subId}\r
 680 \r
 681 \r
 682 **Request Parameters:**\r
 683 \r
 684 +-----------------+---------------------------------+--------------+---------------+--------+-------------+\r
 685 | Field           | Description                     |  Param Type  |  Data Type    | MaxLen |  Required   |\r
 686 +=================+=================================+==============+===============+========+=============+\r
 687 | subscriber      | Subscriber identity as passed   |    Header    |   String      |  <=8   |     Y       |\r
 688 |                 | in X-DMAAP-DR-ON-BEHALF-OF at   |              |               |        |             |\r
 689 |                 | creation time                   |              |               |        |             |\r
 690 +-----------------+---------------------------------+--------------+---------------+--------+-------------+\r
 691 | Authorization   | The user / AppId to be          |    Header    |   String      |        |  Y if AAF   |\r
 692 |                 | authorized by the AAF CADI      |              |               |        |  enabled    |\r
 693 |                 | framework                       |              |               |        |             |\r
 694 +-----------------+---------------------------------+--------------+---------------+--------+-------------+\r
 695 \r
 696 **Response Codes**\r
 697 \r
 698 * Success:\r
 699     200\r
 700 \r
 701 * Error:\r
 702     See `Response Codes`_\r
 703 \r
 704 **Produces**\r
 705     application/json\r
 706 \r
 707 **Sample Request**\r
 708 \r
 709 .. code-block:: bash\r
 710 \r
 711     curl -k -H "X-DMAAP-DR-ON-BEHALF-OF:{user}" https://{host}:{port}/subs/{subId}\r
 712 \r
 713 **Sample Response**\r
 714 \r
 715 .. code-block:: json\r
 716 \r
 717     {\r
 718       "suspend": false,\r
 719       "delivery": {\r
 720         "use100": false,\r
 721         "password": "NEW_PASSWORD",\r
 722         "user": "NEW_LOGIN",\r
 723         "url": "http://dmaap-dr-subscriber:7070/"\r
 724       },\r
 725       "subscriber": "onap",\r
 726       "groupid": 67,\r
 727       "metadataOnly": true,\r
 728       "privilegedSubscriber": false,\r
 729       "follow_redirect": false,\r
 730       "decompress": false,\r
 731       "aaf_instance": "legacy",\r
 732       "links": {\r
 733         "feed": "https://dmaap-dr-prov/feed/2",\r
 734         "log": "https://dmaap-dr-prov/sublog/6",\r
 735         "self": "https://dmaap-dr-prov/subs/6"\r
 736       }\r
 737     }\r
 738 \r
 739 \r
 740 \r
 741 Delete a subscription\r
 742 ---------------------\r
 743 \r
 744 **Description**: Deletes a specified subscription\r
 745 \r
 746 .. code-block:: bash\r
 747 \r
 748     DELETE /subs/{subId}\r
 749 \r
 750 \r
 751 **Request Parameters:**\r
 752 \r
 753 +-----------------+---------------------------------+--------------+---------------+--------+-------------+\r
 754 | Field           | Description                     |  Param Type  |  Data Type    | MaxLen |  Required   |\r
 755 +=================+=================================+==============+===============+========+=============+\r
 756 | subscriber      | Subscriber identity as passed   |     Header   |   String      |  <=8   |     Y       |\r
 757 |                 | in X-DMAAP-DR-ON-BEHALF-OF at   |              |               |        |             |\r
 758 |                 | creation time                   |              |               |        |             |\r
 759 +-----------------+---------------------------------+--------------+---------------+--------+-------------+\r
 760 | Authorization   | The user / AppId to be          |    Header    |   String      |        |  Y if AAF   |\r
 761 |                 | authorized by the AAF CADI      |              |               |        |  enabled    |\r
 762 |                 | framework                       |              |               |        |             |\r
 763 +-----------------+---------------------------------+--------------+---------------+--------+-------------+\r
 764 \r
 765 **Response Codes**\r
 766 \r
 767 * Success:\r
 768     204\r
 769 \r
 770 * Error:\r
 771     See `Response Codes`_\r
 772 \r
 773 **Sample Request**\r
 774 \r
 775 .. code-block:: bash\r
 776 \r
 777     curl -k -X DELETE -H "X-DMAAP-DR-ON-BEHALF-OF:{user}" https://{host}:{port}/subs/{subId}\r
 778 \r
 779 \r
 780 Publish to Feed\r
 781 ---------------\r
 782 \r
 783 **Description**: Publish data to a given feed\r
 784 \r
 785 .. code-block:: bash\r
 786 \r
 787     PUT /publish/{feedId}/{fileId}\r
 788 \r
 789 \r
 790 **Request parameters**\r
 791 \r
 792 +------------------------+---------------------------------+------------------+------------+--------------+-------------+-------------------------------------------+\r
 793 | Name                   | Description                     |  Param Type      |  Data Type |   MaxLen     |  Required   |  Valid/Example Values                     |\r
 794 +========================+=================================+==================+============+==============+=============+===========================================+\r
 795 | feedId                 | ID of the feed you are          |     Path         |   String   |              |     Y       |                                           |\r
 796 |                        | publishing to                   |                  |            |              |             |                                           |\r
 797 +------------------------+---------------------------------+------------------+------------+--------------+-------------+-------------------------------------------+\r
 798 | fileId                 | Name of the file when it is     |     Path         |   String   |              |     Y       |                                           |\r
 799 |                        | published to subscribers        |                  |            |              |             |                                           |\r
 800 +------------------------+---------------------------------+------------------+------------+--------------+-------------+-------------------------------------------+\r
 801 | Content-type           | To specify type of message      |     Header       |   String   |              |     Y       | application/octet-stream                  |\r
 802 |                        | format                          |                  |            |              |             |                                           |\r
 803 +------------------------+---------------------------------+------------------+------------+--------------+-------------+-------------------------------------------+\r
 804 | X-DMAAP-DR-META        | Metadata for the file. Accepts  |     Header       |   String   |   <=4096     |     N       | '{“compressionType”: ”gzip”,              |\r
 805 |                        | only non nested json objects    |                  |            |              |             |   ”id”: 1234,                             |\r
 806 |                        | of the following type:          |                  |            |              |             |   “transferred”: true,                    |\r
 807 |                        |                                 |                  |            |              |             |   “size”: null }’                         |\r
 808 |                        | * Numbers                       |                  |            |              |             |                                           |\r
 809 |                        | * Strings                       |                  |            |              |             |                                           |\r
 810 |                        | * Lowercase boolean             |                  |            |              |             |                                           |\r
 811 |                        | * null                          |                  |            |              |             |                                           |\r
 812 +------------------------+---------------------------------+------------------+------------+--------------+-------------+-------------------------------------------+\r
 813 | Authorization          | An `EID Object`_ with publish   |     Header       |  String    |              |     Y       | * (legacy Feed) dradmin:dradmin           |\r
 814 |                        | permissions.                    |                  |            |              |             | * (AAF Feed) dcae@dcae.onap.org:{password}|\r
 815 |                        | If AAF CADI is enabled, use a   |                  |            |              |             |                                           |\r
 816 |                        | valid AAF user/AppId instead.   |                  |            |              |             |                                           |\r
 817 +------------------------+---------------------------------+------------------+------------+--------------+-------------+-------------------------------------------+\r
 818 \r
 819 **Response Codes**\r
 820 \r
 821 * Success:\r
 822     204\r
 823 \r
 824 * Error:\r
 825     See `Response Codes`_\r
 826 \r
 827 **Sample Request**\r
 828 \r
 829 .. code-block:: bash\r
 830 \r
 831     curl -k -X PUT --user {user}:{password} -H "Content-Type:application/octet-stream"  -H "X-DMAAP-DR-META:{\"filetype\":\"txt\"}" --data-binary @sampleFile.txt --post301 --location-trusted https://{host}:{port}/publish/{feedId}/{fileId}\r
 832 \r
 833 \r
 834 \r
 835 Delete/Retract a Published file\r
 836 -------------------------------\r
 837 \r
 838 **Description**: Deletes/retracts a specified published file\r
 839 \r
 840 .. code-block:: bash\r
 841 \r
 842     DELETE /publish/{feedId}/{fileId}\r
 843 \r
 844 \r
 845 **Request Parameters:**\r
 846 \r
 847 +-----------------+---------------------------------+--------------+---------------+------------+-------------------------------------------+\r
 848 | Field           | Description                     |  Param Type  |  Data Type    | Required   |  Valid/Example Values                     |\r
 849 +=================+=================================+==============+===============+============+===========================================+\r
 850 | Authorization   | An `EID Object`_ with publish   |   Header     |    String     |    Y       | * (legacy Feed) dradmin:dradmin           |\r
 851 |                 | permissions.                    |              |               |            | * (AAF Feed) dcae@dcae.onap.org:{password}|\r
 852 |                 | If AAF CADI is enabled, use a   |              |               |            |                                           |\r
 853 |                 | valid AAF user/AppId instead.   |              |               |            |                                           |\r
 854 +-----------------+---------------------------------+--------------+---------------+------------+-------------------------------------------+\r
 855 | feedId          | ID of the feed that was         |     Path     |    String     |    Y       |                                           |\r
 856 |                 | publishing to                   |              |               |            |                                           |\r
 857 +-----------------+---------------------------------+--------------+---------------+------------+-------------------------------------------+\r
 858 | fileId          | Name of the file when it was    |     Path     |    String     |    Y       |                                           |\r
 859 |                 | published to subscribers        |              |               |            |                                           |\r
 860 +-----------------+---------------------------------+--------------+---------------+------------+-------------------------------------------+\r
 861 \r
 862 **Response Codes**\r
 863 \r
 864 * Success:\r
 865     204\r
 866 \r
 867 * Error:\r
 868     See `Response Codes`_\r
 869 \r
 870 \r
 871 **Sample Request**\r
 872 \r
 873 .. code-block:: bash\r
 874 \r
 875     curl -k -X DELETE --user {user}:{password} --location-trusted https://{host}:{port}/publish/{feedId}/{fileId}\r
 876 \r
 877 \r
 878 \r
 879 Feed logging\r
 880 ------------\r
 881 \r
 882 **Description**: View logging information for specified feeds, which can be narrowed down with further parameters\r
 883 \r
 884 .. code-block:: bash\r
 885 \r
 886     GET /feedlog/{feedId}?{queryParam}\r
 887 \r
 888 \r
 889 **Request parameters**\r
 890 \r
 891 +------------------------+---------------------------------+------------------+------------+-------------+--------------------------------------+\r
 892 | Name                   | Description                     |  Param Type      |  Data Type |  Required   |  Valid/Example Values                |\r
 893 +========================+=================================+==================+============+=============+======================================+\r
 894 | feedId                 | Id of the feed you want         |     Path         |   String   |     Y       | 1                                    |\r
 895 |                        | logs for                        |                  |            |             |                                      |\r
 896 +------------------------+---------------------------------+------------------+------------+-------------+--------------------------------------+\r
 897 | type                   | Select records of the           |     Path         |   String   |     N       | * pub: Publish attempt               |\r
 898 |                        | specified type                  |                  |            |             | * del: Delivery attempt              |\r
 899 |                        |                                 |                  |            |             | * exp: Delivery expiry               |\r
 900 +------------------------+---------------------------------+------------------+------------+-------------+--------------------------------------+\r
 901 | publishId              | Select records with specified   |     Path         |   String   |     N       |                                      |\r
 902 |                        | publish id, carried in the      |                  |            |             |                                      |\r
 903 |                        | X-DMAAP-DR-PUBLISH-ID header    |                  |            |             |                                      |\r
 904 |                        | from original publish request   |                  |            |             |                                      |\r
 905 +------------------------+---------------------------------+------------------+------------+-------------+--------------------------------------+\r
 906 | start                  | Select records created at or    |     Path         |   String   |     N       | A date-time expressed in the format  |\r
 907 |                        | after specified date            |                  |            |             | specified by RFC 3339                |\r
 908 +------------------------+---------------------------------+------------------+------------+-------------+--------------------------------------+\r
 909 | end                    | Select records created at or    |     Path         |   String   |     N       | A date-time expressed in the format  |\r
 910 |                        | before specified date           |                  |            |             | specified by RFC 3339                |\r
 911 +------------------------+---------------------------------+------------------+------------+-------------+--------------------------------------+\r
 912 | statusCode             | Select records with the         |     Path         |   String   |     N       | An HTTP Integer status code or one   |\r
 913 |                        | specified statusCode field      |                  |            |             | of the following special values:     |\r
 914 |                        |                                 |                  |            |             |                                      |\r
 915 |                        |                                 |                  |            |             | * Success: Any code between 200-299  |\r
 916 |                        |                                 |                  |            |             | * Redirect: Any code between 300-399 |\r
 917 |                        |                                 |                  |            |             | * Failure: Any code > 399            |\r
 918 +------------------------+---------------------------------+------------------+------------+-------------+--------------------------------------+\r
 919 | expiryReason           | Select records with the         |     Path         |   String   |     N       |                                      |\r
 920 |                        | specified expiry reason         |                  |            |             |                                      |\r
 921 +------------------------+---------------------------------+------------------+------------+-------------+--------------------------------------+\r
 922 | filename               | Select published records with   |     Path         |   String   |     N       |                                      |\r
 923 |                        | the specified filename          |                  |            |             |                                      |\r
 924 +------------------------+---------------------------------+------------------+------------+-------------+--------------------------------------+\r
 925 \r
 926 **Response Parameters**\r
 927 \r
 928 +------------------------+----------------------------------------------+\r
 929 | Name                   | Description                                  |\r
 930 +========================+==============================================+\r
 931 | type                   | Record type:                                 |\r
 932 |                        |                                              |\r
 933 |                        | * pub: publication attempt                   |\r
 934 |                        | * del: delivery attempt                      |\r
 935 |                        | * exp: delivery expiry                       |\r
 936 +------------------------+----------------------------------------------+\r
 937 | date                   | The UTC date and time at which the record    |\r
 938 |                        | was generated, with millisecond resolution   |\r
 939 |                        | in the format specified by RFC 3339          |\r
 940 +------------------------+----------------------------------------------+\r
 941 | publishId              | The unique identifier assigned by the DR     |\r
 942 |                        | at the time of the initial publication       |\r
 943 |                        | request (carried in the X-DMAAP-DR-PUBLISH-ID|\r
 944 |                        | header in the response to the original       |\r
 945 |                        | publish request)                             |\r
 946 +------------------------+----------------------------------------------+\r
 947 | requestURI             | The Request-URI associated with the          |\r
 948 |                        | request                                      |\r
 949 +------------------------+----------------------------------------------+\r
 950 | method                 | The HTTP method (PUT or DELETE) for the      |\r
 951 |                        | request                                      |\r
 952 +------------------------+----------------------------------------------+\r
 953 | contentType            | The media type of the payload of the         |\r
 954 |                        | request                                      |\r
 955 +------------------------+----------------------------------------------+\r
 956 | contentLength          | The size (in bytes) of the payload of        |\r
 957 |                        | the request                                  |\r
 958 +------------------------+----------------------------------------------+\r
 959 | sourceIp               | The IP address from which the request        |\r
 960 |                        | originated                                   |\r
 961 +------------------------+----------------------------------------------+\r
 962 | endpointId             | The identity used to submit a publish        |\r
 963 |                        | request to the DR                            |\r
 964 +------------------------+----------------------------------------------+\r
 965 | deliveryId             | The identity used to submit a delivery       |\r
 966 |                        | request to a subscriber endpoint             |\r
 967 +------------------------+----------------------------------------------+\r
 968 | statusCode             | The HTTP status code in the response to      |\r
 969 |                        | the request. A value of -1 indicates that    |\r
 970 |                        | the DR was not able to obtain an HTTP        |\r
 971 |                        | status code                                  |\r
 972 +------------------------+----------------------------------------------+\r
 973 | expiryReason           | The reason that delivery attempts were       |\r
 974 |                        | discontinued:                                |\r
 975 |                        |                                              |\r
 976 |                        | * notRetryable: The last delivery attempt    |\r
 977 |                        |   encountered an error condition for which   |\r
 978 |                        |   the DR does not make retries.              |\r
 979 |                        | * retriesExhausted: The DR reached its       |\r
 980 |                        |   limit for making further retry attempts    |\r
 981 +------------------------+----------------------------------------------+\r
 982 | attempts               | Total number of attempts made before         |\r
 983 |                        | delivery attempts were discontinued          |\r
 984 +------------------------+----------------------------------------------+\r
 985 | filename               | File name associated with a publish record   |\r
 986 +------------------------+----------------------------------------------+\r
 987 \r
 988 **Response Codes**\r
 989 \r
 990 * Success:\r
 991     200\r
 992 \r
 993 * Error:\r
 994     See `Response Codes`_\r
 995 \r
 996 **Produces**\r
 997     application/json\r
 998 \r
 999 \r
1000 **Sample Request**\r
1001 \r
1002 .. code-block:: bash\r
1003 \r
1004     curl -k https://{host}:{port}/feedlog/{feedId}?statusCode=204``\r
1005 \r
1006 **Sample Response**\r
1007 \r
1008 .. code-block:: json\r
1009 \r
1010     [\r
1011       {\r
1012         "statusCode": 204,\r
1013         "publishId": "1553715307322.dmaap-dr-node",\r
1014         "requestURI": "https://dmaap-dr-node/publish/1/hello",\r
1015         "sourceIP": "172.19.0.1",\r
1016         "method": "PUT",\r
1017         "contentType": "application/octet-stream",\r
1018         "endpointId": "dradmin",\r
1019         "type": "pub",\r
1020         "date": "2019-03-27T19:35:07.324Z",\r
1021         "contentLength": 14,\r
1022         "fileName": "hello"\r
1023       },\r
1024       {\r
1025         "statusCode": 204,\r
1026         "publishId": "1553715312071.dmaap-dr-node",\r
1027         "requestURI": "https://dmaap-dr-node/publish/2/hello",\r
1028         "sourceIP": "172.19.0.1",\r
1029         "method": "PUT",\r
1030         "contentType": "application/octet-stream",\r
1031         "endpointId": "onap",\r
1032         "type": "pub",\r
1033         "date": "2019-03-27T19:35:12.072Z",\r
1034         "contentLength": 14,\r
1035         "fileName": "hello2"\r
1036       }\r
1037     ]\r
1038 \r
1039 \r
1040 Subscription logging\r
1041 --------------------\r
1042 \r
1043 **Description**: View logging information for specified subscriptions, which can be narrowed down with further parameters\r
1044 \r
1045 .. code-block:: bash\r
1046 \r
1047     GET /sublog/{subId}?{queryParam}\r
1048 \r
1049 \r
1050 **Request parameters**\r
1051 \r
1052 +------------------------+---------------------------------+------------------+------------+-------------+--------------------------------------+\r
1053 | Name                   | Description                     |  Param Type      |  Data Type |  Required   |  Valid/Example Values                |\r
1054 +========================+=================================+==================+============+=============+======================================+\r
1055 | subId                  | Id of the subscription you want |     Path         |   String   |     Y       | 1                                    |\r
1056 |                        | logs for                        |                  |            |             |                                      |\r
1057 +------------------------+---------------------------------+------------------+------------+-------------+--------------------------------------+\r
1058 | type                   | Select records of the           |     Path         |   String   |     N       | * pub: Publish attempt               |\r
1059 |                        | specified type                  |                  |            |             | * del: Delivery attempt              |\r
1060 |                        |                                 |                  |            |             | * exp: Delivery expiry               |\r
1061 +------------------------+---------------------------------+------------------+------------+-------------+--------------------------------------+\r
1062 | publishId              | Select records with specified   |     Path         |   String   |     N       |                                      |\r
1063 |                        | publish id, carried in the      |                  |            |             |                                      |\r
1064 |                        | X-DMAAP-DR-PUBLISH-ID header    |                  |            |             |                                      |\r
1065 |                        | from original publish request   |                  |            |             |                                      |\r
1066 +------------------------+---------------------------------+------------------+------------+-------------+--------------------------------------+\r
1067 | start                  | Select records created at or    |     Path         |   String   |     N       | A date-time expressed in the format  |\r
1068 |                        | after specified date            |                  |            |             | specified by RFC 3339                |\r
1069 +------------------------+---------------------------------+------------------+------------+-------------+--------------------------------------+\r
1070 | end                    | Select records created at or    |     Path         |   String   |     N       | A date-time expressed in the format  |\r
1071 |                        | before specified date           |                  |            |             | specified by RFC 3339                |\r
1072 +------------------------+---------------------------------+------------------+------------+-------------+--------------------------------------+\r
1073 | statusCode             | Select records with the         |     Path         |   String   |     N       | An Http Integer status code or one   |\r
1074 |                        | specified statusCode field      |                  |            |             | of the following special values:     |\r
1075 |                        |                                 |                  |            |             |                                      |\r
1076 |                        |                                 |                  |            |             | * Success: Any code between 200-299  |\r
1077 |                        |                                 |                  |            |             | * Redirect: Any code between 300-399 |\r
1078 |                        |                                 |                  |            |             | * Failure: Any code > 399            |\r
1079 +------------------------+---------------------------------+------------------+------------+-------------+--------------------------------------+\r
1080 | expiryReason           | Select records with the         |     Path         |   String   |     N       |                                      |\r
1081 |                        | specified expiry reason         |                  |            |             |                                      |\r
1082 +------------------------+---------------------------------+------------------+------------+-------------+--------------------------------------+\r
1083 \r
1084 Response Parameters\r
1085 -------------------\r
1086 \r
1087 +------------------------+---------------------------------------------+\r
1088 | Name                   | Description                                 |\r
1089 +========================+=============================================+\r
1090 | type                   | Record type:                                |\r
1091 |                        |                                             |\r
1092 |                        | * pub: publication attempt                  |\r
1093 |                        | * del: delivery attempt                     |\r
1094 |                        | * exp: delivery expiry                      |\r
1095 +------------------------+---------------------------------------------+\r
1096 | date                   | The UTC date and time at which the record   |\r
1097 |                        | was generated, with millisecond resolution  |\r
1098 |                        | in the format specified by RFC 3339         |\r
1099 +------------------------+---------------------------------------------+\r
1100 | publishId              | The unique identifier assigned by the DR    |\r
1101 |                        | at the time of the initial publication      |\r
1102 |                        | request(carried in the X-DMAAP-DR-PUBLISH-ID|\r
1103 |                        | header in the response to the original      |\r
1104 |                        | publish request) to a feed log URL or       |\r
1105 |                        | subscription log URL known to the system    |\r
1106 +------------------------+---------------------------------------------+\r
1107 | requestURI             | The Request-URI associated with the         |\r
1108 |                        | request                                     |\r
1109 +------------------------+---------------------------------------------+\r
1110 | method                 | The HTTP method (PUT or DELETE) for the     |\r
1111 |                        | request                                     |\r
1112 +------------------------+---------------------------------------------+\r
1113 | contentType            | The media type of the payload of the        |\r
1114 |                        | request                                     |\r
1115 +------------------------+---------------------------------------------+\r
1116 | contentLength          | The size (in bytes) of the payload of       |\r
1117 |                        | the request                                 |\r
1118 +------------------------+---------------------------------------------+\r
1119 | sourceIp               | The IP address from which the request       |\r
1120 |                        | originated                                  |\r
1121 +------------------------+---------------------------------------------+\r
1122 | endpointId             | The identity used to submit a publish       |\r
1123 |                        | request to the DR                           |\r
1124 +------------------------+---------------------------------------------+\r
1125 | deliveryId             | The identity used to submit a delivery      |\r
1126 |                        | request to a subscriber endpoint            |\r
1127 +------------------------+---------------------------------------------+\r
1128 | statusCode             | The HTTP status code in the response to     |\r
1129 |                        | the request. A value of -1 indicates that   |\r
1130 |                        | the DR was not able to obtain an HTTP       |\r
1131 |                        | status code                                 |\r
1132 +------------------------+---------------------------------------------+\r
1133 | expiryReason           | The reason that delivery attempts were      |\r
1134 |                        | discontinued:                               |\r
1135 |                        |                                             |\r
1136 |                        | * notRetryable: The last delivery attempt   |\r
1137 |                        |   encountered an error condition for which  |\r
1138 |                        |   the DR does not make retries.             |\r
1139 |                        | * retriesExhausted: The DR reached its      |\r
1140 |                        |   limit for making further retry attempts   |\r
1141 +------------------------+---------------------------------------------+\r
1142 | attempts               | Total number of attempts made before        |\r
1143 |                        | delivery attempts were discontinued         |\r
1144 +------------------------+---------------------------------------------+\r
1145 \r
1146 **Response Codes**\r
1147 \r
1148 * Success:\r
1149     200\r
1150 \r
1151 * Error:\r
1152     See `Response Codes`_\r
1153 \r
1154 **Produces**\r
1155     application/json\r
1156 \r
1157 **Sample Request**\r
1158 \r
1159 .. code-block:: bash\r
1160 \r
1161     curl -k https://{host}:{port}/sublog/{subId}?statusCode=204\r
1162 \r
1163 **Sample Response**\r
1164 \r
1165 .. code-block:: json\r
1166 \r
1167     [\r
1168       {\r
1169         "statusCode": 204,\r
1170         "publishId": "1553715307322.dmaap-dr-node",\r
1171         "requestURI": "https://dmaap-dr-node/publish/1/hello",\r
1172         "sourceIP": "172.19.0.1",\r
1173         "method": "PUT",\r
1174         "contentType": "application/octet-stream",\r
1175         "endpointId": "dradmin",\r
1176         "type": "pub",\r
1177         "date": "2019-03-27T19:35:07.324Z",\r
1178         "contentLength": 14,\r
1179         "fileName": "hello"\r
1180       },\r
1181       {\r
1182         "statusCode": 204,\r
1183         "publishId": "1553715312071.dmaap-dr-node",\r
1184         "requestURI": "https://dmaap-dr-node/publish/2/hello",\r
1185         "sourceIP": "172.19.0.1",\r
1186         "method": "PUT",\r
1187         "contentType": "application/octet-stream",\r
1188         "endpointId": "onap",\r
1189         "type": "pub",\r
1190         "date": "2019-03-27T19:35:12.072Z",\r
1191         "contentLength": 14,\r
1192         "fileName": "hello2"\r
1193       }\r
1194     ]\r
1195 \r
1196 \r
1197 **Feed Authorization Object**\r
1198 \r
1199 .. _`Auth Object`:\r
1200 \r
1201 +----------------+-----------------+--------------------------------+------------------------------+\r
1202 | Field          | Type            | Description                    | Restrictions                 |\r
1203 +================+=================+================================+==============================+\r
1204 | classification | string          | An indicator of the feed’s     | Length <=32                  |\r
1205 |                |                 | data security classification   |                              |\r
1206 +----------------+-----------------+--------------------------------+------------------------------+\r
1207 | endpoint_ids   |`EID Object`_ [] | Array of objects defining the  | At least 1 id in the array   |\r
1208 |                |                 | identities that are allowed    |                              |\r
1209 |                |                 | to publish to this feed        |                              |\r
1210 +----------------+-----------------+--------------------------------+------------------------------+\r
1211 | endpoint_addrs | string[]        | Array of IP addresses or IP    | Each string must be a valid  |\r
1212 |                |                 | subnetwork addresses that      | textual representation of    |\r
1213 |                |                 | are allowed to publish to this | IPv4 or IPv6 host address or |\r
1214 |                |                 | feed; an empty array indicates | subnetwork address.          |\r
1215 |                |                 | that publish requests are      |                              |\r
1216 |                |                 | permitted from any IP address  |                              |\r
1217 +----------------+-----------------+--------------------------------+------------------------------+\r
1218 \r
1219 \r
1220 **Endpoint Identity Object**\r
1221 \r
1222 .. _`EID Object`:\r
1223 \r
1224 +----------+--------+--------------------------+--------------+\r
1225 | Field    | Type   | Description              | Restrictions |\r
1226 +==========+========+==========================+==============+\r
1227 | id       | string | Publishing endpoint      | Length <= 20 |\r
1228 |          |        | identifier               |              |\r
1229 +----------+--------+--------------------------+--------------+\r
1230 | password | string | Password associated with | Length <= 32 |\r
1231 |          |        | id                       |              |\r
1232 +----------+--------+--------------------------+--------------+\r
1233 \r
1234 \r
1235 **Feed Links Object**\r
1236 \r
1237 .. _`Feed Links Obj`:\r
1238 \r
1239 +-----------+---------------------------------------------------+----------------+\r
1240 | Field     | Description                                       | Symbolic Name  |\r
1241 +===========+===================================================+================+\r
1242 | self      | URL pointing to this feed, used for updating and  | <feedURL>      |\r
1243 |           | deleting the feed.                                |                |\r
1244 +-----------+---------------------------------------------------+----------------+\r
1245 | publish   | URL for publishing requests for this feed         | <publishURL>   |\r
1246 +-----------+---------------------------------------------------+----------------+\r
1247 | subscribe | URL for subscribing to this feed                  | <subscribeURL> |\r
1248 +-----------+---------------------------------------------------+----------------+\r
1249 | log       | URL for accessing log information about this feed | <feedLogURL>   |\r
1250 +-----------+---------------------------------------------------+----------------+\r
1251 \r
1252 \r
1253 **Delivery Object**\r
1254 \r
1255 .. _`Del Object`:\r
1256 \r
1257 +----------+---------+-----------------------------------------------+-------------------------------------+\r
1258 |  Field   |  Type   | Description                                   | Restrictions                        |\r
1259 +==========+=========+===============================================+=====================================+\r
1260 |  url     | string  | URL to which deliveries for this subscription | length <= 256                       |\r
1261 |          |         | should be directed Valid HTTPS URL            |                                     |\r
1262 +----------+---------+-----------------------------------------------+-------------------------------------+\r
1263 |  user    | string  | User ID to be passed in the Authorization     | Length <= 20                        |\r
1264 |          |         | header when deliveries are made               |                                     |\r
1265 +----------+---------+-----------------------------------------------+-------------------------------------+\r
1266 | password | string  | Password to be passed in the Authorization    | Length <= 32                        |\r
1267 |          |         | header when deliveries are made               |                                     |\r
1268 +----------+---------+-----------------------------------------------+-------------------------------------+\r
1269 | use100   | boolean | Flag indicating whether the DR should use     | Must be: true to use 100-continue   |\r
1270 |          |         | the HTTP 100-continue feature                 |                                     |\r
1271 |          |         |                                               | false to disable using 100-continue |\r
1272 +----------+---------+-----------------------------------------------+-------------------------------------+\r
1273 \r
1274 \r
1275 **Sub Links Object**\r
1276 \r
1277 .. _`Sub Links Obj`:\r
1278 \r
1279 +-----------+---------------------------------------------------+-------------------+\r
1280 | Field     | Description                                       | Symbolic Name     |\r
1281 +===========+===================================================+===================+\r
1282 | self      | URL pointing to this subscription, used for       | <subscriptionURL> |\r
1283 |           | updating and deleting the subscription.           |                   |\r
1284 +-----------+---------------------------------------------------+-------------------+\r
1285 | feed      | URL of the feed to which this subscription        | <feedURL>         |\r
1286 |           | applies; the same URL as the <feedURL> in the     |                   |\r
1287 |           | representation of the feed                        |                   |\r
1288 +-----------+---------------------------------------------------+-------------------+\r
1289 | log       | URL for accessing log information about this      | <subLogURL>       |\r
1290 |           | subscription                                      |                   |\r
1291 +-----------+---------------------------------------------------+-------------------+\r
1292 \r
1293 \r
1294 **Response/Error Codes**\r
1295 \r
1296 .. _`Response Codes`:\r
1297 \r
1298 +------------------------+-------------------------------------------+\r
1299 | Response statusCode    | Response Description                      |\r
1300 +========================+===========================================+\r
1301 | 200 to 299             | Success Response                          |\r
1302 +------------------------+-------------------------------------------+\r
1303 | 400                    | Bad request - The request is defective in |\r
1304 |                        | some way. Possible causes:                |\r
1305 |                        |                                           |\r
1306 |                        | * JSON object in request body does not    |\r
1307 |                        |   conform to the spec.                    |\r
1308 |                        | * Invalid parameter value in query string |\r
1309 +------------------------+-------------------------------------------+\r
1310 | 401                    | Indicates that the request was missing the|\r
1311 |                        | Authorization header or, if the header    |\r
1312 |                        | was presented, the credentials were not   |\r
1313 |                        | acceptable                                |\r
1314 +------------------------+-------------------------------------------+\r
1315 | 403                    | Forbidden - The request failed            |\r
1316 |                        | authorization.                            |\r
1317 |                        | Possible causes:                          |\r
1318 |                        |                                           |\r
1319 |                        | * Request originated from an unauthorized |\r
1320 |                        |   IP address                              |\r
1321 |                        | * Client certificate subject is not on    |\r
1322 |                        |   the API’s authorized list.              |\r
1323 |                        | * X-DMAAP-DR-ON-BEHALF-OF identity is not |\r
1324 |                        |   authorized to perform                   |\r
1325 +------------------------+-------------------------------------------+\r
1326 | 404                    | Not Found - The Request-URI does not point|\r
1327 |                        | to a resource that is known to the API.   |\r
1328 +------------------------+-------------------------------------------+\r
1329 | 405                    | Method Not Allowed - The HTTP method in   |\r
1330 |                        | the request is not supported for the      |\r
1331 |                        | resource addressed by the Request-URI.    |\r
1332 +------------------------+-------------------------------------------+\r
1333 | 406                    | Not Acceptable - The request has an Accept|\r
1334 |                        | header indicating that the requester will |\r
1335 |                        | not accept a response with                |\r
1336 |                        | application/vnd.dmaap-dr.log-list content.|\r
1337 +------------------------+-------------------------------------------+\r
1338 | 415                    | Unsupported Media Type - The media type in|\r
1339 |                        | the requests Content-Type header is not   |\r
1340 |                        | appropriate for the request.              |\r
1341 +------------------------+-------------------------------------------+\r
1342 | 500                    | Internal Server Error - The DR API server |\r
1343 |                        | encountered an internal error and could   |\r
1344 |                        | not complete the request.                 |\r
1345 +------------------------+-------------------------------------------+\r
1346 | 503                    | Service Unavailable - The DR API service  |\r
1347 |                        | is currently unavailable                  |\r
1348 +------------------------+-------------------------------------------+\r
1349 | -1                     | Failed Delivery                           |\r
1350 +------------------------+-------------------------------------------+