bigchaindb/bigchaindb
1
0
Fork 0
mirror of https://github.com/bigchaindb/bigchaindb.git synced 2024-06-17 18:13:22 +02:00
Code Releases Activity

Merge pull request #2071 from bigchaindb/text-edits-in-http-api-docs

Browse Source 
Copy-edited the HTTP API docs
This commit is contained in:
Troy McConaghy 2018-03-05 12:31:56 +01:00 committed by GitHub
commit 81c6975501
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 102 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

216
docs/server/source/http-client-server-api.rst
View File

@ -50,12 +50,9 @@ Transactions
Get the transaction with the ID ``transaction_id``. Get the transaction with the ID ``transaction_id``.
This endpoint returns a transaction if it was included in a ``VALID`` block. If a transaction with ID ``transaction_id`` has been included
All instances of a transaction in invalid/undecided blocks or the backlog in a committed block, then this endpoint returns that transaction,
are ignored and treated as if they don't exist. If a request is made for a otherwise the response will be ``404 Not Found``.
transaction and instances of that transaction are found only in
invalid/undecided blocks or the backlog, then the response will be ``404 Not
Found``.
:param transaction_id: transaction ID :param transaction_id: transaction ID
:type transaction_id: hex string :type transaction_id: hex string
@ -77,38 +74,27 @@ Transactions
.. http:get:: /api/v1/transactions .. http:get:: /api/v1/transactions
The unfiltered ``/api/v1/transactions`` endpoint without any query parameters Requests to the ``/api/v1/transactions`` endpoint
returns a status code `400`. For valid filters, see the sections below. without any query parameters will get a response status code ``400 Bad Request``.
There are however filtered requests that might come of use, given the endpoint is
queried correctly. Some of them include retrieving a list of transactions
that include:
* `Transactions related to a specific asset <#get--transactions?asset_id=asset_id&operation=CREATE|TRANSFER>`_
In this section, we've listed those particular requests, as they will likely
to be very handy when implementing your application on top of BigchainDB.
.. note::
Looking up transactions with a specific ``metadata`` field is currently not supported,
however, providing a way to query based on ``metadata`` data is on our roadmap.
A generalization of those parameters follows:
:query string asset_id: The ID of the asset.
:query string operation: (Optional) One of the two supported operations of a transaction: ``CREATE``, ``TRANSFER``.
.. http:get:: /api/v1/transactions?asset_id={asset_id}&operation={CREATE|TRANSFER} .. http:get:: /api/v1/transactions?asset_id={asset_id}&operation={CREATE|TRANSFER}
Get a list of transactions that use an asset with the ID ``asset_id``. Get a list of transactions that use an asset with the ID ``asset_id``.
Every ``TRANSFER`` transaction that originates from a ``CREATE`` transaction
with ``asset_id`` will be included. This allows users to query the entire history or If ``operation`` is ``CREATE``, then the CREATE transaction which created
the asset with ID ``asset_id`` will be returned.
If ``operation`` is ``TRANSFER``, then every TRANSFER transaction involving
the asset with ID ``asset_id`` will be returned.
This allows users to query the entire history or
provenance of an asset. provenance of an asset.
This endpoint returns transactions only if they are decided ``VALID`` by the server. If ``operation`` is not included, then *every* transaction involving
the asset with ID ``asset_id`` will be returned.
:query string operation: (Optional) One of the two supported operations of a transaction: ``CREATE``, ``TRANSFER``. This endpoint returns transactions only if they are in committed blocks.
:query string operation: (Optional) ``CREATE`` or ``TRANSFER``.
:query string asset_id: asset ID. :query string asset_id: asset ID.
@ -130,23 +116,36 @@ Transactions
.. http:post:: /api/v1/transactions?mode={mode} .. http:post:: /api/v1/transactions?mode={mode}
Tendermint offers a `broadcast API This endpoint is used to send a transaction to a BigchainDB network.
<http://tendermint.readthedocs.io/projects/tools/en/master/using-tendermint.html#broadcast-api>`_ with three different modes to post transactions. The transaction is put in the body of the request.
By setting the mode, a new transaction can be pushed with a different mode than the default. The default mode is ``async``, which
will return immediately and not wait to see if the transaction is valid. The ``sync`` mode will return after the transaction is validated, while ``commit`` :query string mode: (Optional) One of the three supported modes to send a transaction: ``async``, ``sync``, ``commit``. The default is ``async``.
returns after the transaction is committed to a block.
The ``mode`` query parameter inhereted from the mode parameter in Tendermint's
`broadcast API
<http://tendermint.readthedocs.io/projects/tools/en/master/using-tendermint.html#broadcast-api>`_.
``mode=async`` means the HTTP response will come back immediately, without
even checking to see if the transaction is valid.
``mode=sync`` means the HTTP response will come back once the node has
checked the validity of the transaction.
``mode=commit`` means the HTTP response will come back once the transaction
is in a committed block.
.. note:: .. note::
The posted `transaction The posted transaction should be valid.
<https://docs.bigchaindb.com/projects/server/en/latest/data-models/transaction-model.html>`_ The `IPDB Transaction Spec <https://github.com/ipdb/ipdb-tx-spec>`_
should be structurally valid and not spending an already spent output. explains how to build a valid transaction
The steps to build a valid transaction are beyond the scope of this page. and how to check if a transaction is valid.
One would normally use a driver such as the `BigchainDB Python Driver One would normally use a driver such as the `BigchainDB Python Driver
<https://docs.bigchaindb.com/projects/py-driver/en/latest/index.html>`_ <https://docs.bigchaindb.com/projects/py-driver/en/latest/index.html>`_
to build a valid transaction. to build a valid transaction.
:query string mode: (Optional) One of the three supported modes to send a transaction: ``async``, ``sync``, ``commit``. .. note::
A client can subscribe to the
WebSocket Event Stream API
to listen for committed transactions.
**Example request**: **Example request**:
@ -158,16 +157,12 @@ Transactions
.. literalinclude:: http-samples/post-tx-response.http .. literalinclude:: http-samples/post-tx-response.http
:language: http :language: http
.. note::
If the server is returning a ``202`` HTTP status code when ``mode=aysnc`` or ``mode=sync``, then the
transaction has been accepted for processing. The client can subscribe to the
:ref:`WebSocket Event Stream API <the-websocket-event-stream-api>` to listen for comitted transactions.
:resheader Content-Type: ``application/json`` :resheader Content-Type: ``application/json``
:statuscode 202: The pushed transaction was accepted in the ``BACKLOG``, but the processing has not been completed. :statuscode 202: The meaning of this response depends on the value
:statuscode 400: The transaction was malformed and not accepted in the ``BACKLOG``. of the ``mode`` parameter. See above.
:statuscode 400: The posted transaction was invalid.
.. http:post:: /api/v1/transactions .. http:post:: /api/v1/transactions
@ -195,9 +190,10 @@ unspent outputs.
:param public_key: Base58 encoded public key associated with output :param public_key: Base58 encoded public key associated with output
ownership. This parameter is mandatory and without it ownership. This parameter is mandatory and without it
the endpoint will return a ``400`` response code. the endpoint will return a ``400`` response code.
:param spent: Boolean value ("true" or "false") indicating if the result set :param spent: (Optional) Boolean value (``true`` or ``false``)
indicating if the result set
should include only spent or only unspent outputs. If not should include only spent or only unspent outputs. If not
specified the result includes all the outputs (both spent specified, the result includes all the outputs (both spent
and unspent) associated with the ``public_key``. and unspent) associated with the ``public_key``.
.. http:get:: /api/v1/outputs?public_key={public_key} .. http:get:: /api/v1/outputs?public_key={public_key}
@ -229,7 +225,7 @@ unspent outputs.
} }
] ]
:statuscode 200: A list of outputs were found and returned in the body of the response. :statuscode 200: A list of outputs was found and returned in the body of the response.
:statuscode 400: The request wasn't understood by the server, e.g. the ``public_key`` querystring was not included in the request. :statuscode 400: The request wasn't understood by the server, e.g. the ``public_key`` querystring was not included in the request.
.. http:get:: /api/v1/outputs?public_key={public_key}&spent=true .. http:get:: /api/v1/outputs?public_key={public_key}&spent=true
@ -290,34 +286,37 @@ unspent outputs.
Assets Assets
-------------------------------- ------
.. http:get:: /api/v1/assets .. http:get:: /api/v1/assets
Return all the assets that match a given text search. Return all the assets that match a given text search.
:query string text search: Text search string to query. :query string search: Text search string to query.
:query int limit: (Optional) Limit the number of returned assets. Defaults :query int limit: (Optional) Limit the number of returned assets. Defaults
to ``0`` meaning return all matching assets. to ``0`` meaning return all matching assets.
.. note:: .. note::
Currently this enpoint is only supported if the server is running Currently this endpoint is only supported if using MongoDB.
MongoDB as the backend.
.. http:get:: /api/v1/assets?search={text_search} .. http:get:: /api/v1/assets?search={search}
Return all assets that match a given text search. The ``id`` of the asset Return all assets that match a given text search.
is the same ``id`` of the transaction that created the asset.
.. note::
The ``id`` of the asset
is the same ``id`` of the CREATE transaction that created the asset.
If no assets match the text search it returns an empty list. If no assets match the text search it returns an empty list.
If the text string is empty or the server does not support text search, If the text string is empty or the server does not support text search,
a ``400`` is returned. a ``400 Bad Request`` is returned.
The results are sorted by text score. The results are sorted by text score.
For more information about the behavior of text search see `MongoDB text For more information about the behavior of text search, see `MongoDB text
search behavior <https://docs.mongodb.com/manual/reference/operator/query/text/#behavior>`_ search behavior <https://docs.mongodb.com/manual/reference/operator/query/text/#behavior>`_.
**Example request**: **Example request**:
@ -355,24 +354,24 @@ Assets
text string is empty or the server does not support text string is empty or the server does not support
text search. text search.
.. http:get:: /api/v1/assets?search={text_search}&limit={n_documents} .. http:get:: /api/v1/assets?search={search}&limit={n_documents}
Return at most ``n`` assets that match a given text search. Return at most ``n_documents`` assets that match a given text search.
If no assets match the text search it returns an empty list. If no assets match the text search it returns an empty list.
If the text string is empty or the server does not support text search, If the text string is empty or the server does not support text search,
a ``400`` is returned. a ``400 Bad Request`` is returned.
The results are sorted by text score. The results are sorted by text score.
For more information about the behavior of text search see `MongoDB text For more information about the behavior of text search, see `MongoDB text
search behavior <https://docs.mongodb.com/manual/reference/operator/query/text/#behavior>`_ search behavior <https://docs.mongodb.com/manual/reference/operator/query/text/#behavior>`_.
**Example request**: **Example request**:
.. sourcecode:: http .. sourcecode:: http
GET /api/v1/assets/?search=bigchaindb&limit=2 HTTP/1.1 GET /api/v1/assets?search=bigchaindb&limit=2 HTTP/1.1
Host: example.com Host: example.com
**Example response**: **Example response**:
@ -402,34 +401,37 @@ Assets
Transaction Metadata Transaction Metadata
-------------------------------- --------------------
.. http:get:: /api/v1/metadata .. http:get:: /api/v1/metadata
Return all the metadata that match a given text search. Return all the metadata objects that match a given text search.
:query string text search: Text search string to query. :query string search: Text search string to query.
:query int limit: (Optional) Limit the number of returned metadata objects. Defaults :query int limit: (Optional) Limit the number of returned metadata objects. Defaults
to ``0`` meaning return all matching objects. to ``0`` meaning return all matching objects.
.. note:: .. note::
Currently this enpoint is only supported if the server is running Currently this endpoint is only supported if using MongoDB.
MongoDB as the backend.
.. http:get:: /api/v1/metadata/?search={text_search} .. http:get:: /api/v1/metadata/?search={search}
Return all metadata that match a given text search. The ``id`` of the metadata Return all metadata objects that match a given text search.
is the same ``id`` of the transaction where it was defined.
.. note::
If no metadata match the text search it returns an empty list. The ``id`` of the metadata
is the same ``id`` of the transaction where it was defined.
If no metadata objects match the text search it returns an empty list.
If the text string is empty or the server does not support text search, If the text string is empty or the server does not support text search,
a ``400`` is returned. a ``400 Bad Request`` is returned.
The results are sorted by text score. The results are sorted by text score.
For more information about the behavior of text search see `MongoDB text For more information about the behavior of text search, see `MongoDB text
search behavior <https://docs.mongodb.com/manual/reference/operator/query/text/#behavior>`_ search behavior <https://docs.mongodb.com/manual/reference/operator/query/text/#behavior>`_.
**Example request**: **Example request**:
@ -467,24 +469,24 @@ Transaction Metadata
text string is empty or the server does not support text string is empty or the server does not support
text search. text search.
.. http:get:: /api/v1/metadata/?search={text_search}&limit={n_documents} .. http:get:: /api/v1/metadata/?search={search}&limit={n_documents}
Return at most ``n`` metadata objects that match a given text search. Return at most ``n_documents`` metadata objects that match a given text search.
If no metadata match the text search it returns an empty list. If no metadata objects match the text search it returns an empty list.
If the text string is empty or the server does not support text search, If the text string is empty or the server does not support text search,
a ``400`` is returned. a ``400 Bad Request`` is returned.
The results are sorted by text score. The results are sorted by text score.
For more information about the behavior of text search see `MongoDB text For more information about the behavior of text search, see `MongoDB text
search behavior <https://docs.mongodb.com/manual/reference/operator/query/text/#behavior>`_ search behavior <https://docs.mongodb.com/manual/reference/operator/query/text/#behavior>`_.
**Example request**: **Example request**:
.. sourcecode:: http .. sourcecode:: http
GET /api/v1/metadata/?search=bigchaindb&limit=2 HTTP/1.1 GET /api/v1/metadata?search=bigchaindb&limit=2 HTTP/1.1
Host: example.com Host: example.com
**Example response**: **Example response**:
@ -516,13 +518,8 @@ Transaction Metadata
Advanced Usage Advanced Usage
-------------------------------- --------------------------------
The following endpoints are more advanced and meant for debugging and transparency purposes. The following endpoints are more advanced
and meant for debugging and transparency purposes.
More precisely, the `blocks endpoint <#blocks>`_ allows you to retrieve a block by ``block_id`` as well the list of blocks that
a certain transaction with ``transaction_id`` occured in (a transaction can occur in multiple ``invalid`` blocks until it
either gets rejected or validated by the system). This endpoint gives the ability to drill down on the lifecycle of a
transaction
Blocks Blocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -531,7 +528,7 @@ Blocks
Get the block with the height ``block_height``. Get the block with the height ``block_height``.
:param block_height: block ID :param block_height: block height
:type block_height: integer :type block_height: integer
**Example request**: **Example request**:
@ -547,18 +544,15 @@ Blocks
:resheader Content-Type: ``application/json`` :resheader Content-Type: ``application/json``
:statuscode 200: A block with that ID was found. :statuscode 200: A block with that block height was found.
:statuscode 400: The request wasn't understood by the server, e.g. just requesting ``/blocks`` without the ``block_height``. :statuscode 400: The request wasn't understood by the server, e.g. just requesting ``/blocks`` without the ``block_height``.
:statuscode 404: A block with that ID was not found. :statuscode 404: A block with that block height was not found.
.. http:get:: /api/v1/blocks .. http:get:: /api/v1/blocks
The unfiltered ``/blocks`` endpoint without any query parameters returns a `400` status code. The unfiltered ``/blocks`` endpoint without any query parameters
The list endpoint should be filtered with a ``transaction_id`` query parameter, returns a ``400 Bad Request`` status code.
see the ``/blocks?transaction_id={transaction_id}&status={UNDECIDED|VALID|INVALID}``
`endpoint <#get--blocks?tx_id=tx_id&status=UNDECIDED|VALID|INVALID>`_.
**Example request**: **Example request**:
@ -573,24 +567,18 @@ Blocks
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
:statuscode 400: The request wasn't understood by the server, e.g. just requesting ``/blocks`` without the ``block_id``. :statuscode 400: The request wasn't understood by the server, e.g. just requesting ``/blocks`` without the ``block_height``.
.. http:get:: /api/v1/blocks?transaction_id={transaction_id} .. http:get:: /api/v1/blocks?transaction_id={transaction_id}
Retrieve a list of block IDs (block heights), such that the blocks with those IDs contain a transaction with the ID ``transaction_id``. A correct response may consist of an empty list or a list with one block ID. Retrieve a list of block IDs (block heights), such that the blocks with those IDs contain a transaction with the ID ``transaction_id``. A correct response may consist of an empty list or a list with one block ID.
.. note::
The query parameter ``status`` has been deprecated. It allowed
users to filter blocks based on their status i.e. only blocks with the specified
status were included in the response. Since then this behavior has changed
and now block are created only after the transactions are accepted by the
network i.e. blocks have only one status ``VALID``
.. note:: .. note::
In case no block was found, an empty list and an HTTP status code In case no block was found, an empty list and an HTTP status code
``200 OK`` is returned, as the request was still successful. ``200 OK`` is returned, as the request was still successful.
:query string transaction_id: transaction ID *(required)* :query string transaction_id: (Required) transaction ID
**Example request**: **Example request**:
@ -633,7 +621,7 @@ then the public API Root URL is determined as follows:
- The public IP address (like 12.34.56.78) - The public IP address (like 12.34.56.78)
is the public IP address of the machine exposing is the public IP address of the machine exposing
the HTTP API to the public internet (e.g. either the machine hosting the HTTP API to the public internet (e.g. either the machine hosting
Gunicorn or the machine running the reverse proxy such as Nginx). Gunicorn or the machine running the reverse proxy such as NGINX).
It's determined by AWS, Azure, Rackspace, or whoever is hosting the machine. It's determined by AWS, Azure, Rackspace, or whoever is hosting the machine.
- The DNS hostname (like example.com) is determined by DNS records, - The DNS hostname (like example.com) is determined by DNS records,
@ -641,7 +629,7 @@ then the public API Root URL is determined as follows:
- The port (like 9984) is determined by the ``server.bind`` setting - The port (like 9984) is determined by the ``server.bind`` setting
if Gunicorn is exposed directly to the public Internet. if Gunicorn is exposed directly to the public Internet.
If a reverse proxy (like Nginx) is exposed directly to the public Internet If a reverse proxy (like NGINX) is exposed directly to the public Internet
instead, then it could expose the HTTP API on whatever port it wants to. instead, then it could expose the HTTP API on whatever port it wants to.
(It should expose the HTTP API on port 9984, but it's not bound to do (It should expose the HTTP API on port 9984, but it's not bound to do
that by anything other than convention.) that by anything other than convention.)