From e1bdd410303c5c02bcd0aac273fe18b36f917758 Mon Sep 17 00:00:00 2001 From: Troy McConaghy Date: Mon, 19 Feb 2018 16:33:46 +0100 Subject: [PATCH] Copy-edited the HTTP API docs --- docs/server/source/http-client-server-api.rst | 215 ++++++++---------- 1 file changed, 101 insertions(+), 114 deletions(-) diff --git a/docs/server/source/http-client-server-api.rst b/docs/server/source/http-client-server-api.rst index 6d6cc63a..50e68b42 100644 --- a/docs/server/source/http-client-server-api.rst +++ b/docs/server/source/http-client-server-api.rst @@ -46,12 +46,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 @@ -73,38 +70,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. @@ -126,23 +112,36 @@ Transactions .. http:post:: /api/v1/transactions?mode={mode} - Tendermint offers a `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 + `_. + ``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 - `_ - 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 `_ + 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 `_ 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 + :ref:`WebSocket Event Stream API ` + to listen for committed transactions. **Example request**: @@ -154,15 +153,13 @@ 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 ` 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 @@ -190,9 +187,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} @@ -224,7 +222,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 @@ -285,34 +283,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 `_ + For more information about the behavior of text search, see `MongoDB text + search behavior `_. **Example request**: @@ -350,24 +351,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 `_ + For more information about the behavior of text search, see `MongoDB text + search 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**: @@ -397,34 +398,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 `_ + For more information about the behavior of text search, see `MongoDB text + search behavior `_. **Example request**: @@ -462,24 +466,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 `_ + For more information about the behavior of text search, see `MongoDB text + search 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**: @@ -511,16 +515,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 `votes endpoint <#votes>`_ contains all the voting information for a specific block. So after retrieving the -``block_id`` for a given ``transaction_id``, one can now simply inspect the votes that happened at a specific time on that block. - +The following endpoints are more advanced +and meant for debugging and transparency purposes. Blocks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -529,7 +525,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**: @@ -545,18 +541,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**: @@ -571,24 +564,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**: @@ -631,7 +618,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, @@ -639,7 +626,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.)