From: Emmett Cox Date: Mon, 17 Sep 2018 09:25:09 +0000 (+0100) Subject: User guide documentation for data router X-Git-Tag: 1.0.2~31^2 X-Git-Url: https://gerrit.onap.org/r/gitweb?p=dmaap%2Fdatarouter.git;a=commitdiff_plain;h=8dde0cc7824e32f1a829b1528fa0e61a5707098f User guide documentation for data router Change-Id: If28014e4f937c9036e22f2db7599fd8568f0c13f Signed-off-by: Emmett Cox Issue-ID: DMAAP-552 --- diff --git a/docs/data-router/DataRouterUserGuide.rst b/docs/data-router/DataRouterUserGuide.rst new file mode 100644 index 00000000..8f7b9ef1 --- /dev/null +++ b/docs/data-router/DataRouterUserGuide.rst @@ -0,0 +1,25 @@ +=========================== +Data Router (DR) User Guide +=========================== + +Standalone Mode +--------------- + +Installation +============ + +1. Find the datarouter project on the gerrit website: https://gerrit.onap.org/r/#/admin/projects/dmaap/datarouter + +2. Clone the repo onto your server using the clone command found on the datarouter page on gerrit. + +3. cd into the docker-compose directory and run docker-compose up. + +Configurations +============== + +Using the Data Router +--------------------- + +For information on how to use the Data Router refer to the Data Router API guide at: + + :ref:`data_router_api_guide` \ No newline at end of file diff --git a/docs/data-router/administration.rst b/docs/data-router/administration.rst new file mode 100644 index 00000000..b050a1fe --- /dev/null +++ b/docs/data-router/administration.rst @@ -0,0 +1,14 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Administration +============== + + +Processes +--------- +NA + +Actions +------- +NA diff --git a/docs/data-router/architecture.rst b/docs/data-router/architecture.rst new file mode 100644 index 00000000..b18f7bb3 --- /dev/null +++ b/docs/data-router/architecture.rst @@ -0,0 +1,25 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Architecture +============ + + +Capabilities +------------ +Data Router is a RESTful web service used for the transfer of data across networks any larger than a Message Router message (> 1Mb). + +Usage Scenarios +--------------- + Data Router endpoints are used to create/view/delete Feeds, Subscribers and Published files. Clients can use the Data Router endpoints + to publish a file to a feed and subscribe to this feed to receive the file. + +Interactions +------------ +Data Router REST service uses the Data Router API to allow users to publish to and subscribe to a feed, in order to send and receive files. + + + + |image0| + + .. |image0| image:: dr_arch.png diff --git a/docs/data-router/configuration.rst b/docs/data-router/configuration.rst new file mode 100644 index 00000000..2a7096a1 --- /dev/null +++ b/docs/data-router/configuration.rst @@ -0,0 +1,7 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Configuration +============= + +NA \ No newline at end of file diff --git a/docs/data-router/consumedapis.rst b/docs/data-router/consumedapis.rst new file mode 100644 index 00000000..aa1a8bd1 --- /dev/null +++ b/docs/data-router/consumedapis.rst @@ -0,0 +1,7 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Consumed APIs +============= + +Data Router does not consume any API diff --git a/docs/data-router/data-router.rst b/docs/data-router/data-router.rst index ecce2096..aaee3851 100755 --- a/docs/data-router/data-router.rst +++ b/docs/data-router/data-router.rst @@ -1,10 +1,15 @@ +.. _data_router_api_guide: + ========================== Data Router (DR) API Guide ========================== 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 data producers can make data available to data consumers and a way for potential consumers to find feeds with the data they require. +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 +data producers can make data available to data consumers and a way for potential consumers to find feeds +with the data they require. HTTP Service APIs diff --git a/docs/data-router/delivery.rst b/docs/data-router/delivery.rst new file mode 100644 index 00000000..775841a4 --- /dev/null +++ b/docs/data-router/delivery.rst @@ -0,0 +1,32 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Delivery +============== + +Data Router is comprised of a datarouter-provisioning container, a datarouter-node container and a mariadb container. + +.. blockdiag:: + + + blockdiag layers { + orientation = portrait + MARIADB -> DR-PROV; + DR-PROV -> DR-NODE; + group l1 { + color = blue; + label = "dr-prov Container"; + DR-PROV; + } + group l2 { + color = yellow; + label = "dr-node Container"; + DR-NODE; + } + group l3 { + color = orange; + label = "MariaDb Container"; + MARIADB; + } + + } diff --git a/docs/data-router/dr_arch.png b/docs/data-router/dr_arch.png new file mode 100644 index 00000000..1655edad Binary files /dev/null and b/docs/data-router/dr_arch.png differ diff --git a/docs/data-router/humaninterfaces.rst b/docs/data-router/humaninterfaces.rst new file mode 100644 index 00000000..71a2b730 --- /dev/null +++ b/docs/data-router/humaninterfaces.rst @@ -0,0 +1,10 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Human Interfaces +================ + +Data Router does not have human interfaces + + + diff --git a/docs/data-router/logging.rst b/docs/data-router/logging.rst new file mode 100644 index 00000000..ac6aa95c --- /dev/null +++ b/docs/data-router/logging.rst @@ -0,0 +1,25 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Logging +======= + + +Where to Access Information +--------------------------- +Data Router uses logback framework to generate logs. + +Error / Warning Messages +------------------------ +Currently Data Router does not have any unique error codes. However the following are the common HTTP error codes that +could possibly occur in Data Router: + + OK = 200 : The normal response from a successful update or get of a feed or subscription + CREATED = 201 : the normal response from successfully creating or subscribing to a feed. + NO_CONTENT = 204 : the normal response from a successful publish attempt and on successfully deleting a feed or subscription + MOVED_PERMANENTLY = 301 :the normal redirect response from prov to a publisher + BAD_REQUEST = 400: Usually indicates that either Json object in request body is incorrect in some way, or an Invalid parameter value was included in query string. + UNAUTHORIZED = 401 : Usually indicated either request was missing Authorization header, or indicates incorrect Username/password credentials + FORBIDDEN = 403 : Usually indicates the request originated from an unauthorized IP address, or that a client certificate was not a part of authorized list. + NOT_FOUND = 404 : Usually indicates an incorrect URI + METHOD_NOT_ALLOWED = 405 : Indicates an HTTP method is not accepted for given URI \ No newline at end of file diff --git a/docs/data-router/release-notes.rst b/docs/data-router/release-notes.rst new file mode 100644 index 00000000..f69ea2c8 --- /dev/null +++ b/docs/data-router/release-notes.rst @@ -0,0 +1,29 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Release-notes +============== + +Version: 1.0.1 +-------------- + +:Release Date: 2018-09-20 + + +New Features: + + - Implements a RESTful HTTPS API for creating feeds to publish files to and subscribe to, + as well as perform CRUD operations on these feeds. + - Implements a RESTful HTTPS API for subscribing to feeds and perform CRUD operations on these subscriptions. + - Implements a RESTful HTTPS API for publishing to feeds and perform CRUD operations on these published files. + + + +Bug Fixes +NA + +Known Issues +NA + +Other +NA \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index f7dae490..99f0f281 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,15 +14,24 @@ The DataRouter(DR)provisioning API is an HTTPS-based,REST-like API for creating HTTP Service APIs ------------------ -DMaaP Message 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. +DMaaP Data Router utilizes an HTTPS REST API to service all transactions. HTTPS 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. .. toctree:: - :maxdepth: 3 + :maxdepth: 1 - data-router/data-router + data-router/data-router.rst + data-router/administration.rst + data-router/architecture.rst + data-router/configuration.rst + data-router/consumedapis.rst + data-router/DataRouterUserGuide.rst + data-router/delivery.rst + data-router/humaninterfaces.rst + data-router/logging.rst + data-router/release-notes.rst +