From f70a5356949b00c71580994c4fd97f5af43cc7fd Mon Sep 17 00:00:00 2001 From: efiacor Date: Wed, 23 Jan 2019 16:11:28 +0000 Subject: [PATCH] Bug fix for readTheDocs Change-Id: Ief3eb05307fe18433e03565febd995ae37fd7c82 Issue-ID: DMAAP-976 Signed-off-by: efiacor --- docs/data-router/data-router.rst | 151 +++++++++++++++++++-------------------- 1 file changed, 72 insertions(+), 79 deletions(-) diff --git a/docs/data-router/data-router.rst b/docs/data-router/data-router.rst index 39d61e1c..cd466a7e 100755 --- a/docs/data-router/data-router.rst +++ b/docs/data-router/data-router.rst @@ -7,7 +7,7 @@ Introduction ------------ The DataRouter(DR) provisioning API is an HTTPS-based, REST-like API for creating and managing DR feeds -and subscriptions. The Data Routing System project is intended to provide a common framework by which +and subscriptions. The DMaaP Data Router System project is intended to provide a common framework by which data producers can make data available to data consumers and a way for potential consumers to find feeds with the data they require. @@ -16,15 +16,13 @@ HTTP Service APIs ----------------- DMaaP Data Router utilizes an HTTP REST API to service all transactions. HTTP and REST standards are followed so -clients as varied as CURL, Java applications and even Web Browsers will -work to interact with the Data Router. +clients as varied as CURL, Java applications and even Web Browsers will work to interact with the Data Router. General HTTP Requirements ========================= -A DMaaP Data Router transactions consists of 4 distinct segments, -HTTP URL, HTTP Header, HTTP Body (POST/PUT) and HTTP Response. The general -considerations for each segment are as follows and are required for each +A DMaaP Data Router transactions consists of 4 distinct segments, HTTP URL, HTTP Header, HTTP Body (POST/PUT) +and HTTP Response. The general considerations for each segment are as follows and are required for each of the specific transactions described in this section. HTTP URL @@ -32,8 +30,8 @@ HTTP URL http[s]://{serverBaseURL}/{resourcePath} -* The serverBaseURL points to DMaaP Data Router host/port that will service the request. -* The resourcePath specifies the specific service that the client is attempting to reach. +* The serverBaseURL points to DMaaP Data Router host:port that will service the request. +* The resourcePath specifies the service that the client is attempting to reach. HTTP Header @@ -49,12 +47,12 @@ The HTTP Body contains the feed content when creating a feed. Create a Feed ------------- -**Description**: Creates a unique set of URL's to service the publisher/subscriber model. +**Description**: Creates a unique feed URL to service the publisher/subscriber model. Sample Request ============== -``curl -v -X POST -H "Content-Type: application/vnd.att-dr.feed" -H "X-ATT-DR-ON-BEHALF-OF: {user}" --data-ascii @/opt/app/datartr/addFeed3.txt --post301 --location-trusted -k https:/{host}:{port}`` +``curl -k -X POST -H "Content-Type:application/vnd.att-dr.feed" -H "X-ATT-DR-ON-BEHALF-OF:{user}" --data-ascii @createFeed.json https://{host}:{port}`` Request Parameters: =================== @@ -82,7 +80,7 @@ Request Parameters: | content-type | To specify type of message | Header | String | | Y | application/vnd.att-dr.feed | | | (feed,subscriber,publisher) | | | | | | +------------------------+---------------------------------+------------------+------------+--------------+-------------+--------------------------------------+ -| X-ATT-DR-ON-BEHALF-OF | User id of owner of feed | Header | String | 8 | Y | username | +| X-ATT-DR-ON-BEHALF-OF | User id of owner of feed | Header | String | <=8 | Y | username | +------------------------+---------------------------------+------------------+------------+--------------+-------------+--------------------------------------+ Response/Error Codes @@ -142,27 +140,24 @@ Sample Body { "name": "Jettydemo", - "version": "m1.0", + "version": "v1.0.0", "description": "Jettydemo", "business_description": "Jettydemo", "suspend": false, - "deleted": false, "changeowner": true, "authorization": { "classification": "unclassified", - "endpoint_addrs": [ - "172.18.0.3", - ], + "endpoint_addrs": ["172.18.0.3","192.167.3.42"], "endpoint_ids": [ { "password": "password", "id": "user" } ] - }, - + } } + Updating a Feed --------------- @@ -171,7 +166,7 @@ Updating a Feed Sample Request ============== -``curl -v -X PUT -H "Content-Type: application/vnd.att-dr.feed" -H "X-ATT-DR-ON-BEHALF-OF: {user}" --data-ascii @/opt/app/datartr/addFeed3.txt --location-trusted -k https:/{host}:{port}`` +``curl -k -X PUT -H "Content-Type: application/vnd.att-dr.feed" -H "X-ATT-DR-ON-BEHALF-OF: {user}" --data-ascii @updateFeed.json --location-trusted https://{host}:{port}/feed/{feedId}`` Request Parameters: =================== @@ -195,7 +190,7 @@ Request Parameters: | content-type | To specify type of message | Header | String | | Y | application/vnd.att-dr.feed | | | (feed,subscriber,publisher) | | | | | | +------------------------+---------------------------------+------------------+------------+--------------+-------------+--------------------------------------+ -| X-ATT-DR-ON-BEHALF-OF | User id of owner of feed | Header | String | 8 | Y | username | +| X-ATT-DR-ON-BEHALF-OF | User id of owner of feed | Header | String | <=8 | Y | username | +------------------------+---------------------------------+------------------+------------+--------------+-------------+--------------------------------------+ Response/Error Codes @@ -255,27 +250,24 @@ Sample Body { "name": "Jettydemo", - "version": "m1.0", - "description": "Jettydemo", - "business_description": "Jettydemo", + "version": "v1.0.0", + "description": "Updated decription", + "business_description": "Updated business description", "suspend": false, - "deleted": false, "changeowner": true, "authorization": { "classification": "unclassified", - "endpoint_addrs": [ - "172.18.0.3", - ], + "endpoint_addrs": ["172.18.0.3","192.167.3.42"], "endpoint_ids": [ { "password": "password", "id": "user" } ] - }, - + } } + Get a Feed ---------- @@ -291,7 +283,7 @@ http[s]://{host}:{port}/feed/{feedId} Sample Request ============== -``curl -v -X GET -H "X-ATT-DR-ON-BEHALF-OF: {user}" --location-trusted -k https:/{host}:{port}/feed/{feedId}`` +``curl -k -H "X-ATT-DR-ON-BEHALF-OF: {user}" https://{host}:{port}/feed/{feedId}`` Response/Error Codes ==================== @@ -352,7 +344,7 @@ http[s]://{host}:{port}/feed/{feedId} Sample Request ============== -``curl -v -X DELETE -H "X-ATT-DR-ON-BEHALF-OF: {user}" --location-trusted -k https:/{host}:{port}/feed/{feedId}`` +``curl -k -X DELETE -H "X-ATT-DR-ON-BEHALF-OF: {user}" https://{host}:{port}/feed/{feedId}`` Response/Error Codes ==================== @@ -409,10 +401,12 @@ Request URL http[s]://{host}:{port}/subscribe/{feedId} +* {feedId}: Id of the feed to subscribe to + Sample Request ============== -``curl -v -X POST -H "Content-Type: application/vnd.att-dr.subscription" -H "X-ATT-DR-ON-BEHALF-OF: {user}" --data-ascii @/opt/app/datartr/addSubscriber.txt --post301 --location-trusted -k https://{host}:{port}/subscribe/{feedId}`` +``curl -k -X POST -H "Content-Type:application/vnd.att-dr.subscription" -H "X-ATT-DR-ON-BEHALF-OF:{user}" --data-ascii @addSubscriber.json https://{host}:{port}/subscribe/{feedId}`` Request Parameters: =================== @@ -441,7 +435,7 @@ Request Parameters: | content-type | To specify type of message | Header | String | | Y | application/vnd.att-dr.subscription | | | (feed,subscriber,publisher) | | | | | | +------------------------+---------------------------------+------------------+------------+--------------+-------------+--------------------------------------+ -| X-ATT-DR-ON-BEHALF-OF | User id of subscriber | Header | String | 8 | Y | username | +| X-ATT-DR-ON-BEHALF-OF | User id of subscriber | Header | String | <=8 | Y | username | +------------------------+---------------------------------+------------------+------------+--------------+-------------+--------------------------------------+ Response/Error Codes @@ -507,10 +501,8 @@ Sample Body "use100" : true }, "metadataOnly" : false, - "suspend" : false, - "groupid" : 29, - "subscriber" : "subscriber123" - + "groupid" : 1, + "subscriber" : "subuser" } Update subscription @@ -521,12 +513,14 @@ Update subscription Request URL =========== -http[s]://{host}:{port}/subscribe/{feedId} +http[s]://{host}:{port}/subs/{subId} + +* {subId}: Id of the subscription to be updated Sample Request ============== -``curl -v -X PUT -H "Content-Type: application/vnd.att-dr.subscription" -H "X-ATT-DR-ON-BEHALF-OF: {user}" --data-ascii @/opt/app/datartr/addSubscriber.txt --location-trusted -k https://{host}:{port}/subscribe/{feedId}`` +``curl -k -X PUT -H "Content-Type:application/vnd.att-dr.subscription" -H "X-ATT-DR-ON-BEHALF-OF:{user}" --data-ascii @updateSubscriber.json https://{host}:{port}/subs/{subId}`` Request Parameters: =================== @@ -534,7 +528,7 @@ Request Parameters: +------------------------+---------------------------------+------------------+------------+--------------+-------------+--------------------------------------+ | Name | Description | Param Type | Data Type | MaxLen | Required | Valid/Example Values | +========================+=================================+==================+============+==============+=============+======================================+ -| feedId | ID for the subscription you are | Path | String | | Y | | +| subId | ID for the subscription you are | Path | String | | Y | | | | updating | | | | | | +------------------------+---------------------------------+------------------+------------+--------------+-------------+--------------------------------------+ | delivery | Address and credentials for | Body | Object | | Y | | @@ -615,16 +609,14 @@ Sample Body { "delivery" :{ - "url" : "http://172.18.0.3:7070/", - "user" : "LOGIN", - "password" : "PASSWORD", + "url" : "http://192.0.0.1:7070/", + "user" : "NEW_LOGIN", + "password" : "NEW_PASSWORD", "use100" : true }, "metadataOnly" : false, - "suspend" : false, - "groupid" : 29, - "subscriber" : "subscriber123" - + "groupid" : 2, + "subscriber" : "subuser" } @@ -636,14 +628,14 @@ Get a Subscription Request URL =========== -http[s]://{host}:{port}/subscribe/{subId} +http[s]://{host}:{port}/subs/{subId} * {subId}: Id of the subscription you want to see a representation of Sample Request ============== -``curl -v -X GET -H "X-ATT-DR-ON-BEHALF-OF: {user}" --location-trusted -k https:/{host}:{port}/subscribe/{subId}`` +``curl -k -H "X-ATT-DR-ON-BEHALF-OF:{user}" https://{host}:{port}/subs/{subId}`` Response/Error Codes ==================== @@ -697,14 +689,14 @@ Delete a subscription Request URL =========== -http[s]://{host}:{port}/feed/{feedId} +http[s]://{host}:{port}/subs/{subId} -* {feedId}: Id of the subscription you want to delete +* {subId}: Id of the subscription you want to delete Sample Request ============== -``curl -v -X DELETE -H "X-ATT-DR-ON-BEHALF-OF: {user}" --location-trusted -k https:/{host}:{port}/subscribe/{feedId}`` +``curl -k -X DELETE -H "X-ATT-DR-ON-BEHALF-OF:{user}" https://{host}:{port}/subs/{subId}`` Response/Error Codes ==================== @@ -753,16 +745,20 @@ Response/Error Codes Publish to Feed --------------- -**Description**: Publish a file to a created feed so that it can be shared to any subscribers of that feed +**Description**: Publish data to a given feed Request URL =========== http[s]://{host}:{port}/publish/{feedId}/{fileName} -* {feedId} is the id of the feed you are publishing to. -* {fileId} is the id of the file you are publishing onto the feed. +* {feedId} The id of the feed you are publishing to. +* {fileId} The name of the file you are publishing to the feed. +Sample Request +============== + +``curl -k -X PUT --user {user}:{password} -H "Content-Type:application/octet-stream" -H "X-ATT-DR-META:{\"filetype\":\"txt\"}" --data-binary @sampleFile.txt --post301 --location-trusted https://{host}:{port}/publish/{feedId}/sampleFile`` Request parameters ================== @@ -817,10 +813,6 @@ Response/Error Codes | | available | +------------------------+---------------------------------+ -Sample Request -============== - -``curl -v -X PUT --user {user}:{password} -H "Content-Type: application/octet-stream" -H X-ATT-DR-META:'{"filetype":"zip"}' --data-binary @/opt/app/datartr/sampleFile.txt --post301 --location-trusted -k https://{host}:{port}/publish/{feedId}/sampleFile.txt`` Delete a Published file ----------------------- @@ -838,7 +830,7 @@ http[s]://{host}:{port}/publish/{feedId}/{fileId} Sample Request ============== -``curl -v -X DELETE -H "X-ATT-DR-ON-BEHALF-OF: {user}" --location-trusted -k https:/{host}:{port}/publish/{feedId}/{fileId}`` +``curl -k -X DELETE --user {user}:{password} --location-trusted https://{host}:{port}/publish/{feedId}/{fileId}`` Response/Error Codes ==================== @@ -877,11 +869,16 @@ Feed logging Request URL =========== - http[s]://{host}:{port}/feedlog/{feedId}?{queryParameter} -* {feedId} : The id of the feed you want to get logs from -* {queryParameter}: A parameter passed through to narrow the returned logs. multiple parameters can be passed +* {feedId} : The id of the feed you want to get logs for +* {queryParameter}: A parameter passed through to narrow the returned logs. Multiple parameters can be passed. + + +Sample Request +============== + +``curl -k https://{host}:{port}/feedlog/{feedId}?statusCode=204`` Request parameters ================== @@ -890,7 +887,7 @@ Request parameters | Name | Description | Param Type | Data Type | MaxLen | Required | Valid/Example Values | +========================+=================================+==================+============+==============+=============+======================================+ | feedId | Id of the feed you want | Path | String | | N | 1 | -| | logs from | | | | | | +| | logs for | | | | | | +------------------------+---------------------------------+------------------+------------+--------------+-------------+--------------------------------------+ | type | Select records of the | Path | String | | N | * pub: Publish attempt | | | specified type | | | | | * del: Delivery attempt | @@ -1014,12 +1011,8 @@ Response/Error Codes | | is currently unavailable | +------------------------+-------------------------------------------+ -Sample Request -============== -``curl -v -k https://{host}:{port}/feedlog/{feedId}?statusCode=204`` - -Subscriber logging +Subscription logging ------------------ **Description**: View logging information for specified subscriptions, which can be narrowed down with further parameters @@ -1027,11 +1020,16 @@ Subscriber logging Request URL =========== - http[s]://{host}:{port}/sublog/{subId}?{queryParameter} * {subId}: The id of the feed you want to get logs from -* {queryParameter}: A parameter passed through to narrow the returned logs. multiple parameters can be passed +* {queryParameter}: A parameter passed through to narrow the returned logs. Multiple parameters can be passed. + + +Sample Request +============== + +``curl -k https://{host}:{port}/sublog/{subId}?statusCode=204`` Request parameters ================== @@ -1039,8 +1037,8 @@ Request parameters +------------------------+---------------------------------+------------------+------------+--------------+-------------+--------------------------------------+ | Name | Description | Param Type | Data Type | MaxLen | Required | Valid/Example Values | +========================+=================================+==================+============+==============+=============+======================================+ -| subId | Id of the feed you want | Path | String | | N | 1 | -| | logs from | | | | | | +| subId | Id of the subscription you want | Path | String | | N | 1 | +| | logs for | | | | | | +------------------------+---------------------------------+------------------+------------+--------------+-------------+--------------------------------------+ | type | Select records of the | Path | String | | N | * pub: Publish attempt | | | specified type | | | | | * del: Delivery attempt | @@ -1087,7 +1085,7 @@ Response Parameters +------------------------+-------------------------------------------+ | publishId | The unique identifier assigned by the DR | | | at the time of the initial publication | -| | request (carried in the X-ATT-DRPUBLISH-ID| +| | request(carried in the X-ATT-DR-PUBLISH-ID| | | header in the response to the original | | | publish request) to a feed log URL or | | | subscription log URL known to the system | @@ -1165,8 +1163,3 @@ Response/Error Codes | 503 | Service Unavailable - The DR API service | | | is currently unavailable | +------------------------+-------------------------------------------+ - -Sample Request -============== - -``curl -v -k https://{host}:{port}/sublog/{subscriberId}?statusCode=204`` -- 2.16.6