mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
Merge branch 'tendermint' into tendermint-docs-k8s-dep
This commit is contained in:
Ahmed Muawia Khan
@@ -31,7 +31,7 @@ with something like the following in the body:
|
||||
.. _api-root-endpoint:
|
||||
|
||||
API Root Endpoint
|
||||
-------------------
|
||||
-----------------
|
||||
|
||||
If you send an HTTP GET request to the API Root Endpoint
|
||||
e.g. ``http://localhost:9984/api/v1/``
|
||||
@@ -44,7 +44,7 @@ that allows you to discover the BigchainDB API endpoints:
|
||||
|
||||
|
||||
Transactions
|
||||
-------------------
|
||||
------------
|
||||
|
||||
.. http:get:: /api/v1/transactions/{transaction_id}
|
||||
|
||||
@@ -138,10 +138,6 @@ Transactions
|
||||
|
||||
.. note::
|
||||
|
||||
This option is only available when using BigchainDB with Tendermint.
|
||||
|
||||
.. 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.
|
||||
@@ -163,15 +159,12 @@ Transactions
|
||||
:language: http
|
||||
|
||||
.. note::
|
||||
If the server is returning a ``202`` HTTP status code, then the
|
||||
transaction has been accepted for processing. To check the status of the
|
||||
transaction, poll the link to the
|
||||
:ref:`status monitor <get_status_of_transaction>`
|
||||
provided in the ``Location`` header or listen to server's
|
||||
:ref:`WebSocket Event Stream API <the-websocket-event-stream-api>`.
|
||||
|
||||
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 Location: Relative link to a status monitor for the submitted transaction.
|
||||
|
||||
: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``.
|
||||
@@ -179,7 +172,8 @@ Transactions
|
||||
|
||||
.. http:post:: /api/v1/transactions
|
||||
|
||||
This endpoint (without any parameters) will push a new transaction. If BigchainDB is used with Tendermint, the default mode ``async`` is used.
|
||||
This endpoint (without any parameters) will push a new transaction.
|
||||
Since no ``mode`` parameter is included, the default mode is assumed: ``async``.
|
||||
|
||||
|
||||
Transaction Outputs
|
||||
@@ -295,71 +289,6 @@ unspent outputs.
|
||||
:statuscode 400: The request wasn't understood by the server, e.g. the ``public_key`` querystring was not included in the request.
|
||||
|
||||
|
||||
Statuses
|
||||
--------------------------------
|
||||
|
||||
.. http:get:: /api/v1/statuses
|
||||
|
||||
Get the status of an asynchronously written transaction or block by their id.
|
||||
|
||||
:query string transaction_id: transaction ID
|
||||
:query string block_id: block ID
|
||||
|
||||
.. note::
|
||||
|
||||
Exactly one of the ``transaction_id`` or ``block_id`` query parameters must be
|
||||
used together with this endpoint (see below for getting `transaction
|
||||
statuses <#get--statuses?tx_id=tx_id>`_ and `block statuses
|
||||
<#get--statuses?block_id=block_id>`_).
|
||||
|
||||
.. _get_status_of_transaction:
|
||||
|
||||
.. http:get:: /api/v1/statuses?transaction_id={transaction_id}
|
||||
|
||||
Get the status of a transaction.
|
||||
|
||||
The possible status values are ``undecided``, ``valid`` or ``backlog``.
|
||||
If a transaction in neither of those states is found, a ``404 Not Found``
|
||||
HTTP status code is returned. `We're currently looking into ways to unambigously let the user know about a transaction's status that was included in an invalid block. <https://github.com/bigchaindb/bigchaindb/issues/1039>`_
|
||||
|
||||
**Example request**:
|
||||
|
||||
.. literalinclude:: http-samples/get-statuses-tx-request.http
|
||||
:language: http
|
||||
|
||||
**Example response**:
|
||||
|
||||
.. literalinclude:: http-samples/get-statuses-tx-valid-response.http
|
||||
:language: http
|
||||
|
||||
:resheader Content-Type: ``application/json``
|
||||
|
||||
:statuscode 200: A transaction with that ID was found.
|
||||
:statuscode 404: A transaction with that ID was not found.
|
||||
|
||||
|
||||
.. http:get:: /api/v1/statuses?block_id={block_id}
|
||||
|
||||
Get the status of a block.
|
||||
|
||||
The possible status values are ``undecided``, ``valid`` or ``invalid``.
|
||||
|
||||
**Example request**:
|
||||
|
||||
.. literalinclude:: http-samples/get-statuses-block-request.http
|
||||
:language: http
|
||||
|
||||
**Example response**:
|
||||
|
||||
.. literalinclude:: http-samples/get-statuses-block-valid-response.http
|
||||
:language: http
|
||||
|
||||
:resheader Content-Type: ``application/json``
|
||||
|
||||
:statuscode 200: A block with that ID was found.
|
||||
:statuscode 404: A block with that ID was not found.
|
||||
|
||||
|
||||
Assets
|
||||
--------------------------------
|
||||
|
||||
@@ -594,9 +523,6 @@ a certain transaction with ``transaction_id`` occured in (a transaction can occu
|
||||
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.
|
||||
|
||||
|
||||
Blocks
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@@ -682,37 +608,6 @@ Blocks
|
||||
:statuscode 400: The request wasn't understood by the server, e.g. just requesting ``/blocks``, without defining ``transaction_id``.
|
||||
|
||||
|
||||
Votes
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. http:get:: /api/v1/votes?block_id={block_id}
|
||||
|
||||
Retrieve a list of votes for a certain block with ID ``block_id``.
|
||||
To check for the validity of a vote, a user of this endpoint needs to
|
||||
perform the `following steps: <https://github.com/bigchaindb/bigchaindb/blob/8ebd93ed3273e983f5770b1617292aadf9f1462b/bigchaindb/util.py#L119>`_
|
||||
|
||||
1. Check if the vote's ``node_pubkey`` is allowed to vote.
|
||||
2. Verify the vote's signature against the vote's body (``vote.vote``) and ``node_pubkey``.
|
||||
|
||||
|
||||
:query string block_id: The block ID to filter the votes.
|
||||
|
||||
**Example request**:
|
||||
|
||||
.. literalinclude:: http-samples/get-vote-request.http
|
||||
:language: http
|
||||
|
||||
**Example response**:
|
||||
|
||||
.. literalinclude:: http-samples/get-vote-response.http
|
||||
:language: http
|
||||
|
||||
:resheader Content-Type: ``application/json``
|
||||
|
||||
:statuscode 200: A list of votes voting for a block with ID ``block_id`` was found and returned.
|
||||
:statuscode 400: The request wasn't understood by the server, e.g. just requesting ``/votes``, without defining ``block_id``.
|
||||
|
||||
|
||||
.. _determining-the-api-root-url:
|
||||
|
||||
Determining the API Root URL
|
||||
|
||||
Reference in New Issue
Block a user