Mirroristas/bigchaindb
2
0
Fork 0
mirror of https://github.com/bigchaindb/bigchaindb.git synced 2024-10-13 13:34:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #757 from bigchaindb/update-http-api-docs

Browse Source 
Updated the docs page about the HTTP API
This commit is contained in:
Troy McConaghy 2016-10-28 12:04:58 +02:00 committed by GitHub
commit c1aa19935d
1 changed files with 168 additions and 177 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

345
docs/server/source/drivers-clients/http-client-server-api.rst
View File

@ -1,7 +1,9 @@
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. .. 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.
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: 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:
@ -11,6 +13,10 @@ but that address can be changed by changing the "API endpoint" configuration set
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 BigchainDB Configuration Settings <../server-reference/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 :doc:`the section about BigchainDB Configuration Settings <../server-reference/configuration>`.
API Root
--------
If you send an HTTP GET request to e.g. ``http://localhost:9984`` (with no ``/api/v1/`` on the end), then you should get an HTTP response with something like the following in the body: If you send an HTTP GET request to e.g. ``http://localhost:9984`` (with no ``/api/v1/`` on the end), then you should get an HTTP response with something like the following in the body:
.. code-block:: json .. code-block:: json
@ -27,87 +33,134 @@ If you send an HTTP GET request to e.g. ``http://localhost:9984`` (with no ``/ap
} }
HTTP API Endpoints POST /transactions/
------------------ -------------------
.. http:get:: /transactions/{tx_id} .. http:post:: /transactions/
Get the transaction with the ID ``tx_id``. Push a new transaction.
This endpoint returns only a transaction from a ``VALID`` or ``UNDECIDED`` block on ``bigchain``, if exists. Note: The posted transaction should be valid `transaction <https://bigchaindb.readthedocs.io/en/latest/data-models/transaction-model.html>`_. The steps to build a valid transaction are beyond the scope of this page. One would normally use a driver such as the `BigchainDB Python Driver <https://docs.bigchaindb.com/projects/py-driver/en/latest/index.html>`_ to build a valid transaction.
:param tx_id: transaction ID
:type tx_id: hex string
**Example request**: **Example request**:
.. sourcecode:: http .. sourcecode:: http
GET /transactions/7ad5a4b83bc8c70c4fd7420ff3c60693ab8e6d0e3124378ca69ed5acd2578792 HTTP/1.1 POST /transactions/ HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/json
{
"transaction": {
"conditions": [
{
"cid": 0,
"condition": {
"uri": "cc:4:20:GG-pi3CeIlySZhQoJVBh9O23PzrOuhnYI7OHqIbHjkk:96",
"details": {
"signature": null,
"type": "fulfillment",
"type_id": 4,
"bitmask": 32,
"public_key": "2ePYHfV3yS3xTxF9EE3Xjo8zPwq2RmLPFAJGQqQKc3j6"
}
},
"amount": 1,
"owners_after": [
"2ePYHfV3yS3xTxF9EE3Xjo8zPwq2RmLPFAJGQqQKc3j6"
]
}
],
"operation": "CREATE",
"asset": {
"divisible": false,
"updatable": false,
"data": null,
"id": "aebeab22-e672-4d3b-a187-bde5fda6533d",
"refillable": false
},
"metadata": null,
"timestamp": "1477578978",
"fulfillments": [
{
"fid": 0,
"input": null,
"fulfillment": "cf:4:GG-pi3CeIlySZhQoJVBh9O23PzrOuhnYI7OHqIbHjkn2VnQaEWvecO1x82Qr2Va_JjFywLKIOEV1Ob9Ofkeln2K89ny2mB-s7RLNvYAVzWNiQnp18_nQEUsvwACEXTYJ",
"owners_before": [
"2ePYHfV3yS3xTxF9EE3Xjo8zPwq2RmLPFAJGQqQKc3j6"
]
}
]
},
"id": "2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e",
"version": 1
}
**Example response**: **Example response**:
.. sourcecode:: http .. sourcecode:: http
HTTP/1.1 200 OK HTTP/1.1 201 Created
Content-Type: application/json Content-Type: application/json
{ {
"id":"7ad5a4b83bc8c70c4fd7420ff3c60693ab8e6d0e3124378ca69ed5acd2578792", "id": "2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e",
"transaction":{ "version": 1,
"conditions":[ "transaction": {
{ "conditions": [
"cid":0, {
"condition":{ "amount": 1,
"details":{ "condition": {
"bitmask":32, "uri": "cc:4:20:GG-pi3CeIlySZhQoJVBh9O23PzrOuhnYI7OHqIbHjkk:96",
"public_key":"CwA8s2QYQBfNz4WvjEwmJi83zYr7JhxRhidx6uZ5KBVd", "details": {
"signature":null, "signature": null,
"type":"fulfillment", "type_id": 4,
"type_id":4 "type": "fulfillment",
}, "bitmask": 32,
"uri":"cc:4:20:sVA_3p8gvl8yRFNTomqm6MaavKewka6dGYcFAuPrRXQ:96" "public_key": "2ePYHfV3yS3xTxF9EE3Xjo8zPwq2RmLPFAJGQqQKc3j6"
},
"owners_after":[
"CwA8s2QYQBfNz4WvjEwmJi83zYr7JhxRhidx6uZ5KBVd"
]
} }
], },
"data":{ "owners_after": [
"payload":null, "2ePYHfV3yS3xTxF9EE3Xjo8zPwq2RmLPFAJGQqQKc3j6"
"uuid":"a9999d69-6cde-4b80-819d-ed57f6abe257" ],
}, "cid": 0
"fulfillments":[ }
{ ],
"owners_before":[ "fulfillments": [
"JEAkEJqLbbgDRAtMm8YAjGp759Aq2qTn9eaEHUj2XePE" {
], "input": null,
"fid":0, "fulfillment": "cf:4:GG-pi3CeIlySZhQoJVBh9O23PzrOuhnYI7OHqIbHjkn2VnQaEWvecO1x82Qr2Va_JjFywLKIOEV1Ob9Ofkeln2K89ny2mB-s7RLNvYAVzWNiQnp18_nQEUsvwACEXTYJ",
"fulfillment":"cf:4:__Y_Um6H73iwPe6ejWXEw930SQhqVGjtAHTXilPp0P01vE_Cx6zs3GJVoO1jhPL18C94PIVkLTGMUB2aKC9qsbIb3w8ejpOf0_I3OCuTbPdkd6r2lKMeVftMyMxkeWoM", "fid": 0,
"input":{ "owners_before": [
"cid":0, "2ePYHfV3yS3xTxF9EE3Xjo8zPwq2RmLPFAJGQqQKc3j6"
"txid":"598ce4e9a29837a1c6fc337ee4a41b61c20ad25d01646754c825b1116abd8761" ]
} }
} ],
], "operation": "CREATE",
"operation":"TRANSFER", "timestamp": "1477578978",
"timestamp":"1471423869", "asset": {
"version":1 "updatable": false,
} "refillable": false,
"divisible": false,
"data": null,
"id": "aebeab22-e672-4d3b-a187-bde5fda6533d"
},
"metadata": null
}
} }
:statuscode 200: A transaction with that ID was found. :statuscode 201: A new transaction was created.
:statuscode 404: A transaction with that ID was not found. :statuscode 400: The transaction was invalid and not created.
GET /transactions/{tx_id}/status
--------------------------------
.. http:get:: /transactions/{tx_id}/status .. http:get:: /transactions/{tx_id}/status
Get the status of a transaction with the ID ``tx_id``. Get the status of the transaction with the ID ``tx_id``, if a transaction with that ``tx_id`` exists.
This endpoint returns the status of a transaction if exists. The possible status values are ``backlog``, ``undecided``, ``valid`` or ``invalid``.
Possible values are ``valid``, ``invalid``, ``undecided`` or ``backlog``.
:param tx_id: transaction ID :param tx_id: transaction ID
:type tx_id: hex string :type tx_id: hex string
@ -133,140 +186,78 @@ HTTP API Endpoints
:statuscode 200: A transaction with that ID was found and the status is returned. :statuscode 200: A transaction with that ID was found and the status is returned.
:statuscode 404: A transaction with that ID was not found. :statuscode 404: A transaction with that ID was not found.
.. http:post:: /transactions/
Push a new transaction. GET /transactions/{tx_id}
-------------------------
.. http:get:: /transactions/{tx_id}
Get the transaction with the ID ``tx_id``.
This endpoint returns only a transaction from a ``VALID`` or ``UNDECIDED`` block on ``bigchain``, if exists.
:param tx_id: transaction ID
:type tx_id: hex string
**Example request**: **Example request**:
.. sourcecode:: http .. sourcecode:: http
POST /transactions/ HTTP/1.1 GET /transactions/2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/json
{
"id":"7ad5a4b83bc8c70c4fd7420ff3c60693ab8e6d0e3124378ca69ed5acd2578792",
"transaction":{
"conditions":[
{
"cid":0,
"condition":{
"details":{
"bitmask":32,
"public_key":"CwA8s2QYQBfNz4WvjEwmJi83zYr7JhxRhidx6uZ5KBVd",
"signature":null,
"type":"fulfillment",
"type_id":4
},
"uri":"cc:4:20:sVA_3p8gvl8yRFNTomqm6MaavKewka6dGYcFAuPrRXQ:96"
},
"owners_after":[
"CwA8s2QYQBfNz4WvjEwmJi83zYr7JhxRhidx6uZ5KBVd"
]
}
],
"data":{
"payload":null,
"uuid":"a9999d69-6cde-4b80-819d-ed57f6abe257"
},
"fulfillments":[
{
"owners_before":[
"JEAkEJqLbbgDRAtMm8YAjGp759Aq2qTn9eaEHUj2XePE"
],
"fid":0,
"fulfillment":"cf:4:__Y_Um6H73iwPe6ejWXEw930SQhqVGjtAHTXilPp0P01vE_Cx6zs3GJVoO1jhPL18C94PIVkLTGMUB2aKC9qsbIb3w8ejpOf0_I3OCuTbPdkd6r2lKMeVftMyMxkeWoM",
"input":{
"cid":0,
"txid":"598ce4e9a29837a1c6fc337ee4a41b61c20ad25d01646754c825b1116abd8761"
}
}
],
"operation":"TRANSFER",
"timestamp":"1471423869",
"version":1
}
}
**Example response**: **Example response**:
.. sourcecode:: http .. sourcecode:: http
HTTP/1.1 201 Created HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
{ {
"assignee":"4XYfCbabAWVUCbjTmRTFEu2sc3dFEdkse4r6X498B1s8", "transaction": {
"id":"7ad5a4b83bc8c70c4fd7420ff3c60693ab8e6d0e3124378ca69ed5acd2578792", "conditions": [
"transaction":{ {
"conditions":[ "cid": 0,
{ "condition": {
"cid":0, "uri": "cc:4:20:GG-pi3CeIlySZhQoJVBh9O23PzrOuhnYI7OHqIbHjkk:96",
"condition":{ "details": {
"details":{ "signature": null,
"bitmask":32, "type": "fulfillment",
"public_key":"CwA8s2QYQBfNz4WvjEwmJi83zYr7JhxRhidx6uZ5KBVd", "type_id": 4,
"signature":null, "bitmask": 32,
"type":"fulfillment", "public_key": "2ePYHfV3yS3xTxF9EE3Xjo8zPwq2RmLPFAJGQqQKc3j6"
"type_id":4
},
"uri":"cc:4:20:sVA_3p8gvl8yRFNTomqm6MaavKewka6dGYcFAuPrRXQ:96"
},
"owners_after":[
"CwA8s2QYQBfNz4WvjEwmJi83zYr7JhxRhidx6uZ5KBVd"
]
} }
], },
"data":{ "amount": 1,
"payload":null, "owners_after": [
"uuid":"a9999d69-6cde-4b80-819d-ed57f6abe257" "2ePYHfV3yS3xTxF9EE3Xjo8zPwq2RmLPFAJGQqQKc3j6"
}, ]
"fulfillments":[ }
{ ],
"owners_before":[ "operation": "CREATE",
"JEAkEJqLbbgDRAtMm8YAjGp759Aq2qTn9eaEHUj2XePE" "asset": {
], "divisible": false,
"fid":0, "updatable": false,
"fulfillment":"cf:4:__Y_Um6H73iwPe6ejWXEw930SQhqVGjtAHTXilPp0P01vE_Cx6zs3GJVoO1jhPL18C94PIVkLTGMUB2aKC9qsbIb3w8ejpOf0_I3OCuTbPdkd6r2lKMeVftMyMxkeWoM", "data": null,
"input":{ "id": "aebeab22-e672-4d3b-a187-bde5fda6533d",
"cid":0, "refillable": false
"txid":"598ce4e9a29837a1c6fc337ee4a41b61c20ad25d01646754c825b1116abd8761" },
} "metadata": null,
} "timestamp": "1477578978",
], "fulfillments": [
"operation":"TRANSFER", {
"timestamp":"1471423869", "fid": 0,
"version":1 "input": null,
} "fulfillment": "cf:4:GG-pi3CeIlySZhQoJVBh9O23PzrOuhnYI7OHqIbHjkn2VnQaEWvecO1x82Qr2Va_JjFywLKIOEV1Ob9Ofkeln2K89ny2mB-s7RLNvYAVzWNiQnp18_nQEUsvwACEXTYJ",
"owners_before": [
"2ePYHfV3yS3xTxF9EE3Xjo8zPwq2RmLPFAJGQqQKc3j6"
]
}
]
},
"id": "2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e",
"version": 1
} }
:statuscode 201: A new transaction was created. :statuscode 200: A transaction with that ID was found.
:statuscode 400: The transaction was invalid and not created. :statuscode 404: A transaction with that ID was not found.
**Disclaimer**
``CREATE`` transactions are treated differently from ``TRANSFER`` assets.
The reason is that a ``CREATE`` transaction needs to be signed by a federation node and not by the client.
The following python snippet in a client can be used to generate ``CREATE`` transactions before they can be pushed to the API server:
.. code-block:: python
from bigchaindb import util
tx = util.create_and_sign_tx(my_privkey, my_pubkey, my_pubkey, None, 'CREATE')
When POSTing ``tx`` to the API, the ``CREATE`` transaction will be signed by a federation node.
A ``TRANSFER`` transaction, that takes an existing input transaction to change ownership can be generated in multiple ways:
.. code-block:: python
from bigchaindb import util, Bigchain
tx = util.create_and_sign_tx(my_privkey, my_pubkey, other_pubkey, input_tx, 'TRANSFER')
# or
b = Bigchain()
tx_unsigned = b.create_transaction(my_pubkey, other_pubkey, input_tx, 'TRANSFER')
tx = b.sign_transaction(tx_unsigned, my_privkey)
More information on generating transactions can be found in the `Python server API examples <python-server-api-examples.html>`_