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