bigchaindb
/
bigchaindb
mirror of https://github.com/bigchaindb/bigchaindb.git
1
0
Fork 0
Code Releases Activity

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

Copy-edited the HTTP API docs
This commit is contained in:
Troy McConaghy 2018-03-05 12:31:56 +01:00 committed by GitHub
parent c2fd9e7b7b 497e1039ef
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``.
This endpoint returns a transaction if it was included in a ``VALID`` block.
All instances of a transaction in invalid/undecided blocks or the backlog
are ignored and treated as if they don't exist. If a request is made for a
transaction and instances of that transaction are found only in
invalid/undecided blocks or the backlog, then the response will be ``404 Not
Found``.
If a transaction with ID ``transaction_id`` has been included
in a committed block, then this endpoint returns that transaction,
otherwise the response will be ``404 Not Found``.
:param transaction_id: transaction ID
:type transaction_id: hex string
@ -77,38 +74,27 @@ Transactions
.. http:get:: /api/v1/transactions
The unfiltered ``/api/v1/transactions`` endpoint without any query parameters
returns a status code `400`. For valid filters, see the sections below.
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``.
Requests to the ``/api/v1/transactions`` endpoint
without any query parameters will get a response status code ``400 Bad Request``.
.. 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``.
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.
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.
@ -130,23 +116,36 @@ Transactions
.. http:post:: /api/v1/transactions?mode={mode}
Tendermint offers a `broadcast API
<http://tendermint.readthedocs.io/projects/tools/en/master/using-tendermint.html#broadcast-api>`_ with three different modes to post transactions.
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``
returns after the transaction is committed to a block.
This endpoint is used to send a transaction to a BigchainDB network.
The transaction is put in the body of the request.
:query string mode: (Optional) One of the three supported modes to send a transaction: ``async``, ``sync``, ``commit``. The default is ``async``.
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::
The posted `transaction
<https://docs.bigchaindb.com/projects/server/en/latest/data-models/transaction-model.html>`_
should be structurally valid and not spending an already spent output.
The steps to build a valid transaction are beyond the scope of this page.
The posted transaction should be valid.
The `IPDB Transaction Spec <https://github.com/ipdb/ipdb-tx-spec>`_
explains how to build a valid transaction
and how to check if a transaction is valid.
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.
: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**:
@ -158,16 +157,12 @@ Transactions
.. literalinclude:: http-samples/post-tx-response.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``
:statuscode 202: The pushed transaction was accepted in the ``BACKLOG``, but the processing has not been completed.
:statuscode 400: The transaction was malformed and not accepted in the ``BACKLOG``.
:statuscode 202: The meaning of this response depends on the value
of the ``mode`` parameter. See above.
:statuscode 400: The posted transaction was invalid.
.. http:post:: /api/v1/transactions
@ -195,9 +190,10 @@ unspent outputs.
:param public_key: Base58 encoded public key associated with output
ownership. This parameter is mandatory and without it
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
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``.
.. 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.
.. http:get:: /api/v1/outputs?public_key={public_key}&spent=true
@ -290,34 +286,37 @@ unspent outputs.
Assets
--------------------------------
------
.. http:get:: /api/v1/assets
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
to ``0`` meaning return all matching assets.
.. note::
Currently this enpoint is only supported if the server is running
MongoDB as the backend.
Currently this endpoint is only supported if using MongoDB.
.. 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
is the same ``id`` of the transaction that created the asset.
Return all assets that match a given text search.
.. 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 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.
For more information about the behavior of text search see `MongoDB text
search behavior <https://docs.mongodb.com/manual/reference/operator/query/text/#behavior>`_
For more information about the behavior of text search, see `MongoDB text
search behavior <https://docs.mongodb.com/manual/reference/operator/query/text/#behavior>`_.
**Example request**:
@ -355,24 +354,24 @@ Assets
text string is empty or the server does not support
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 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.
For more information about the behavior of text search see `MongoDB text
search behavior <https://docs.mongodb.com/manual/reference/operator/query/text/#behavior>`_
For more information about the behavior of text search, see `MongoDB text
search behavior <https://docs.mongodb.com/manual/reference/operator/query/text/#behavior>`_.
**Example request**:
.. 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
**Example response**:
@ -402,34 +401,37 @@ Assets
Transaction 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
to ``0`` meaning return all matching objects.
.. note::
Currently this enpoint is only supported if the server is running
MongoDB as the backend.
Currently this endpoint is only supported if using MongoDB.
.. 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
is the same ``id`` of the transaction where it was defined.
Return all metadata objects that match a given text search.
.. 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,
a ``400`` is returned.
a ``400 Bad Request`` is returned.
The results are sorted by text score.
For more information about the behavior of text search see `MongoDB text
search behavior <https://docs.mongodb.com/manual/reference/operator/query/text/#behavior>`_
For more information about the behavior of text search, see `MongoDB text
search behavior <https://docs.mongodb.com/manual/reference/operator/query/text/#behavior>`_.
**Example request**:
@ -467,24 +469,24 @@ Transaction Metadata
text string is empty or the server does not support
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,
a ``400`` is returned.
a ``400 Bad Request`` is returned.
The results are sorted by text score.
For more information about the behavior of text search see `MongoDB text
search behavior <https://docs.mongodb.com/manual/reference/operator/query/text/#behavior>`_
For more information about the behavior of text search, see `MongoDB text
search behavior <https://docs.mongodb.com/manual/reference/operator/query/text/#behavior>`_.
**Example request**:
.. 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
**Example response**:
@ -516,13 +518,8 @@ Transaction Metadata
Advanced Usage
--------------------------------
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
The following endpoints are more advanced
and meant for debugging and transparency purposes.
Blocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -531,7 +528,7 @@ Blocks
Get the block with the height ``block_height``.
:param block_height: block ID
:param block_height: block height
:type block_height: integer
**Example request**:
@ -547,18 +544,15 @@ Blocks
: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 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
The unfiltered ``/blocks`` endpoint without any query parameters returns a `400` status code.
The list endpoint should be filtered with a ``transaction_id`` query parameter,
see the ``/blocks?transaction_id={transaction_id}&status={UNDECIDED|VALID|INVALID}``
`endpoint <#get--blocks?tx_id=tx_id&status=UNDECIDED|VALID|INVALID>`_.
The unfiltered ``/blocks`` endpoint without any query parameters
returns a ``400 Bad Request`` status code.
**Example request**:
@ -573,24 +567,18 @@ Blocks
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}
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::
In case no block was found, an empty list and an HTTP status code
``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**:
@ -633,7 +621,7 @@ then the public API Root URL is determined as follows:
- The public IP address (like 12.34.56.78)
is the public IP address of the machine exposing
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.
- 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
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.
(It should expose the HTTP API on port 9984, but it's not bound to do
that by anything other than convention.)