From b8357c8df092be151e6e12f7adf16a54d5a2b016 Mon Sep 17 00:00:00 2001 From: troymc Date: Thu, 14 Jul 2016 11:32:42 +0200 Subject: [PATCH 1/4] Add sphinxcontrib-httpdomain extension --- docs/requirements.txt | 1 + docs/source/conf.py | 1 + .../{http-client-server-api.md => http-client-server-api.rst} | 0 3 files changed, 2 insertions(+) rename docs/source/drivers-clients/{http-client-server-api.md => http-client-server-api.rst} (100%) diff --git a/docs/requirements.txt b/docs/requirements.txt index 9e6b6214..b322aa58 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,3 +2,4 @@ Sphinx==1.3.5 sphinxcontrib-napoleon==0.4.4 sphinx-rtd-theme>=0.1.9 recommonmark +sphinxcontrib-httpdomain==1.5.0 diff --git a/docs/source/conf.py b/docs/source/conf.py index be078160..ba599796 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -42,6 +42,7 @@ extensions = [ 'sphinx.ext.coverage', 'sphinx.ext.viewcode', 'sphinxcontrib.napoleon', + 'sphinxcontrib.httpdomain', ] # autodoc settings diff --git a/docs/source/drivers-clients/http-client-server-api.md b/docs/source/drivers-clients/http-client-server-api.rst similarity index 100% rename from docs/source/drivers-clients/http-client-server-api.md rename to docs/source/drivers-clients/http-client-server-api.rst From 9c17a6df84af95ad4911539bec4dcc2afc2cbff9 Mon Sep 17 00:00:00 2001 From: troymc Date: Thu, 14 Jul 2016 11:33:51 +0200 Subject: [PATCH 2/4] Docs: move HTTP API docs from Apiary to /docs --- .../http-client-server-api.rst | 70 ++++++++++++++++--- 1 file changed, 61 insertions(+), 9 deletions(-) diff --git a/docs/source/drivers-clients/http-client-server-api.rst b/docs/source/drivers-clients/http-client-server-api.rst index 35da0426..71700ea6 100644 --- a/docs/source/drivers-clients/http-client-server-api.rst +++ b/docs/source/drivers-clients/http-client-server-api.rst @@ -1,17 +1,69 @@ -# The HTTP Client-Server API +The HTTP Client-Server API +========================== -Note: The HTTP client-server API is currently quite rudimentary. For example, there is no ability to do complex queries using the HTTP API. We plan to add querying capabilities in the future. If you want to build a full-featured proof-of-concept, we suggest you use [the Python server API](../nodes/python-server-api-examples.html) for now. +Note: The HTTP client-server API is currently quite rudimentary. For example, there is no ability to do complex queries using the HTTP API. We plan to add querying capabilities in the future. If you want to build a full-featured proof-of-concept, we suggest you use :doc:`the Python Server API <../nodes/python-server-api-examples>` for now. When you start Bigchaindb using `bigchaindb start`, an HTTP API is exposed at the address stored in the BigchainDB node configuration settings. The default is for that address to be: -[http://localhost:9984/api/v1/](http://localhost:9984/api/v1/) +`http://localhost:9984/api/v1/ `_ -but that address can be changed by changing the "API endpoint" configuration setting (e.g. in a local config file). There's more information about setting the API endpoint in [the section about Configuring a BigchainDB Node](../nodes/configuration.html). +but that address can be changed by changing the "API endpoint" configuration setting (e.g. in a local config file). There's more information about setting the API endpoint in :doc:`the section about Configuring a BigchainDB Node <../nodes/configuration>`. -There are other configuration settings related to the web server (serving the HTTP API). In particular, the default is for the web server socket to bind to `localhost:9984` but that can be changed (e.g. to `0.0.0.0:9984`). For more details, see the "server" settings ("bind", "workers" and "threads") in [the section about Configuring a BigchainDB Node](../nodes/configuration.html). +There are other configuration settings related to the web server (serving the HTTP API). In particular, the default is for the web server socket to bind to `localhost:9984` but that can be changed (e.g. to `0.0.0.0:9984`). For more details, see the "server" settings ("bind", "workers" and "threads") in :doc:`the section about Configuring a BigchainDB Node <../nodes/configuration>`. -The HTTP API currently exposes two endpoints, one to get information about a -specific transaction id, and one to push a transaction to the BigchainDB -cluster. Those endpoints are documented at: +The HTTP API currently exposes two endpoints, one to get information about a specific transaction, and one to push a new transaction to the BigchainDB cluster. -[http://docs.bigchaindb.apiary.io/](http://docs.bigchaindb.apiary.io/) +.. http:get:: /transactions/(tx_id) + + The transaction with the transaction ID `tx_id`. + + **Example request**: + + .. sourcecode:: http + + GET /transactions/00f530d210c06671ab2de4330e3e2cf0d0b47b2826302ee25ceea9b2f47b097f HTTP/1.1 + Host: example.com + TODO: Other headers? + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + TODO: Other headers? + + (TODO) Insert example response body here + + :statuscode 200: A transaction with that ID was found. + :statuscode 404: A transaction with that ID was not found. + + +.. http:post:: /transactions/ + + Push a new transaction. + + **Example request**: + + .. sourcecode:: http + + POST /transactions/ HTTP/1.1 + Host: example.com + Content-Type: application/json + TODO: Other headers? + + (TODO) Insert example request body here + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 201 Created + Content-Type: application/json + TODO: Other headers? + + (TODO) Insert example response body here + + :statuscode 201: A new transaction was created. + +(TODO) What's the response status code if the POST fails? From 7c9efbf321c38b37249b536f15870540a3ce8fcd Mon Sep 17 00:00:00 2001 From: troymc Date: Thu, 14 Jul 2016 11:44:28 +0200 Subject: [PATCH 3/4] Make Python docs package reqs consistent between setup.py & requirements.txt --- docs/requirements.txt | 8 ++++---- setup.py | 5 +++-- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index b322aa58..542ff3d2 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,5 @@ -Sphinx==1.3.5 -sphinxcontrib-napoleon==0.4.4 +Sphinx>=1.3.5 +recommonmark>=0.4.0 sphinx-rtd-theme>=0.1.9 -recommonmark -sphinxcontrib-httpdomain==1.5.0 +sphinxcontrib-napoleon>=0.4.4 +sphinxcontrib-httpdomain>=1.5.0 diff --git a/setup.py b/setup.py index 602bd184..a6539a34 100644 --- a/setup.py +++ b/setup.py @@ -45,10 +45,11 @@ dev_require = [ ] docs_require = [ - 'recommonmark>=0.4.0', 'Sphinx>=1.3.5', - 'sphinxcontrib-napoleon>=0.4.4', + 'recommonmark>=0.4.0', 'sphinx-rtd-theme>=0.1.9', + 'sphinxcontrib-napoleon>=0.4.4', + 'sphinxcontrib-httpdomain>=1.5.0', ] benchmarks_require = [ From ac4912b40937fca98e6e604dfdedc0bb9ea41be8 Mon Sep 17 00:00:00 2001 From: troymc Date: Thu, 14 Jul 2016 13:24:30 +0200 Subject: [PATCH 4/4] Docs: Added example HTTP API GET response --- .../http-client-server-api.rst | 20 +++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/source/drivers-clients/http-client-server-api.rst b/docs/source/drivers-clients/http-client-server-api.rst index 71700ea6..ab038657 100644 --- a/docs/source/drivers-clients/http-client-server-api.rst +++ b/docs/source/drivers-clients/http-client-server-api.rst @@ -21,7 +21,7 @@ The HTTP API currently exposes two endpoints, one to get information about a spe .. sourcecode:: http - GET /transactions/00f530d210c06671ab2de4330e3e2cf0d0b47b2826302ee25ceea9b2f47b097f HTTP/1.1 + GET /transactions/96480ce68912aa39a54766ac16334a835fbf777039670352ff967bf6d65bf4f7 HTTP/1.1 Host: example.com TODO: Other headers? @@ -33,7 +33,23 @@ The HTTP API currently exposes two endpoints, one to get information about a spe Content-Type: application/json TODO: Other headers? - (TODO) Insert example response body here + {'id': '96480ce68912aa39a54766ac16334a835fbf777039670352ff967bf6d65bf4f7', + 'transaction': {'conditions': [{'cid': 0, + 'condition': {'details': {'bitmask': 32, + 'public_key': 'FoWUUY6kK7QhgCsgVrV2vpDWfW43mq5ewb16Uh7FBbSF', + 'signature': None, + 'type': 'fulfillment', + 'type_id': 4}, + 'uri': 'cc:4:20:2-2pA2qKr2i-GM6REdqJCLEL_CEWpy-5iQky7YgRZTA:96'}, + 'new_owners': ['FoWUUY6kK7QhgCsgVrV2vpDWfW43mq5ewb16Uh7FBbSF']}], + 'data': {'payload': None, 'uuid': 'f14dc5a6-510e-4307-89c6-aec42af8a1ae'}, + 'fulfillments': [{'current_owners': ['Ftat68WVLsPxVFLz2Rh2Sbwrrt51uFE3UpjkxY73vGKZ'], + 'fid': 0, + 'fulfillment': 'cf:4:3TqMI1ZFolraqHWADT6nIvUUt4HOwqdr0_-yj5Cglbg1V5qQV2CF2Yup1l6fQH2uhLGGFo9uHhZ6HNv9lssiD0ZaG88Bg_MTkz6xg2SW2Cw_YgpM-CyESVT404g54ZsK', + 'input': None}], + 'operation': 'CREATE', + 'timestamp': '1468494923'}, + 'version': 1} :statuscode 200: A transaction with that ID was found. :statuscode 404: A transaction with that ID was not found.