The HTTP Client-Server API¶
This page assumes you already know an API Root URL
for a BigchainDB node or reverse proxy.
It should be something like https://example.com:9984
or https://12.34.56.78:9984
.
If you set up a BigchainDB node or reverse proxy yourself, and you’re not sure what the API Root URL is, then see the last section of this page for help.
BigchainDB Root URL¶
If you send an HTTP GET request to the BigchainDB Root URL
e.g. http://localhost:9984
or https://example.com:9984
(with no /api/v1/
on the end),
then you should get an HTTP response
with something like the following in the body:
HTTP/1.1 200 OK
Content-Type: application/json
{
"api": {
"v1": {
"assets": "/api/v1/assets/",
"docs": "https://docs.bigchaindb.com/projects/server/en/v1.2.0/http-client-server-api.html",
"outputs": "/api/v1/outputs/",
"statuses": "/api/v1/statuses/",
"streams": "ws://localhost:9985/api/v1/streams/valid_transactions",
"transactions": "/api/v1/transactions/"
}
},
"docs": "https://docs.bigchaindb.com/projects/server/en/v1.2.0/",
"keyring": [
"6qHyZew94NMmUTYyHnkZsB8cxJYuRNEiEpXHe1ih9QX3",
"AdDuyrTyjrDt935YnFu4VBCVDhHtY2Y6rcy7x2TFeiRi"
],
"public_key": "NC8c8rYcAhyKVpx1PCV65CBmyq4YUbLysy3Rqrg8L8mz",
"software": "BigchainDB",
"version": "1.2.0"
}
API Root Endpoint¶
If you send an HTTP GET request to the API Root Endpoint
e.g. http://localhost:9984/api/v1/
or https://example.com:9984/api/v1/
,
then you should get an HTTP response
that allows you to discover the BigchainDB API endpoints:
HTTP/1.1 200 OK
Content-Type: application/json
{
"assets": "/assets/",
"docs": "https://docs.bigchaindb.com/projects/server/en/v1.2.0/http-client-server-api.html",
"outputs": "/outputs/",
"statuses": "/statuses/",
"streams": "ws://localhost:9985/api/v1/streams/valid_transactions",
"transactions": "/transactions/"
}
Transactions¶
-
GET
/api/v1/transactions/{transaction_id}
¶ 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 be404 Not Found
.Parameters: - transaction_id (hex string) – transaction ID
Example request:
GET /api/v1/transactions/8b20dbe164badd5ca0611b0e233aef9acce609fbca20f787fc7d926f300d0102 HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "asset": { "data": { "msg": "Hello BigchainDB!" } }, "id": "8b20dbe164badd5ca0611b0e233aef9acce609fbca20f787fc7d926f300d0102", "inputs": [ { "fulfillment": "pGSAIDE5i63cn4X8T8N1sZ2mGkJD5lNRnBM4PZgI_zvzbr-cgUCGvCc2HO2uB4IKix6INRzGIM10r7VsKFMPM9cT7uVJ1xFLOJ9bn6UioepBMLIrrwTlk2CkTolIPonf7BnzriQL", "fulfills": null, "owners_before": [ "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD" ] } ], "metadata": { "sequence": 0 }, "operation": "CREATE", "outputs": [ { "amount": "1", "condition": { "details": { "public_key": "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD", "type": "ed25519-sha-256" }, "uri": "ni:///sha-256;PNYwdxaRaNw60N6LDFzOWO97b8tJeragczakL8PrAPc?fpt=ed25519-sha-256&cost=131072" }, "public_keys": [ "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD" ] } ], "version": "1.0" }
Response Headers: - Content-Type –
application/json
Status Codes: - 200 OK – A transaction with that ID was found.
- 404 Not Found – A transaction with that ID was not found.
-
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:
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 onmetadata
data is on our roadmap.A generalization of those parameters follows:
Query Parameters: - asset_id (string) – The ID of the asset.
- operation (string) – (Optional) One of the two supported operations of a transaction:
CREATE
,TRANSFER
.
-
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
. EveryTRANSFER
transaction that originates from aCREATE
transaction withasset_id
will be included. 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.Query Parameters: - operation (string) – (Optional) One of the two supported operations of a transaction:
CREATE
,TRANSFER
. - asset_id (string) – asset ID.
Example request:
GET /api/v1/transactions?operation=TRANSFER&asset_id=8b20dbe164badd5ca0611b0e233aef9acce609fbca20f787fc7d926f300d0102 HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-Type: application/json [{ "asset": { "id": "8b20dbe164badd5ca0611b0e233aef9acce609fbca20f787fc7d926f300d0102" }, "id": "7d3ed7e5bcad27b878a4e3f25363c8b03f49fa5007f6e6032d9ec38e36bc2e83", "inputs": [ { "fulfillment": "pGSAIDE5i63cn4X8T8N1sZ2mGkJD5lNRnBM4PZgI_zvzbr-cgUA11pDN83PjcBhuH-ICqy6cbyxeXrHQBgHXhbulDInXoMPsVeOJp65Wsxr0WO6kmJvwgA7Je1UgzNJZ6pWb3kcL", "fulfills": { "output_index": 0, "transaction_id": "8b20dbe164badd5ca0611b0e233aef9acce609fbca20f787fc7d926f300d0102" }, "owners_before": [ "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD" ] } ], "metadata": { "sequence": 1 }, "operation": "TRANSFER", "outputs": [ { "amount": "1", "condition": { "details": { "public_key": "3yfQPHeWAa1MxTX9Zf9176QqcpcnWcanVZZbaHb8B3h9", "type": "ed25519-sha-256" }, "uri": "ni:///sha-256;lu6ov4AKkee6KWGnyjOVLBeyuP0bz4-O6_dPi15eYUc?fpt=ed25519-sha-256&cost=131072" }, "public_keys": [ "3yfQPHeWAa1MxTX9Zf9176QqcpcnWcanVZZbaHb8B3h9" ] } ], "version": "1.0" }, { "asset": { "id": "8b20dbe164badd5ca0611b0e233aef9acce609fbca20f787fc7d926f300d0102" }, "id": "d07285a60352838ff263a46ba8cca64e18d36888aee0ba76d5d601137b492fc6", "inputs": [ { "fulfillment": "pGSAICw7Ul-c2lG6NFbHp3FbKRC7fivQcNGO7GS4wV3A-1QggUBRFFWoFwJhWGhbt02I3NPIBT84qzNB1-dTyuj1zvUfVmY7fn1GAqI6A6pPRch36hYF4Gup2R0DFdAitEHxhB4K", "fulfills": { "output_index": 0, "transaction_id": "7d3ed7e5bcad27b878a4e3f25363c8b03f49fa5007f6e6032d9ec38e36bc2e83" }, "owners_before": [ "3yfQPHeWAa1MxTX9Zf9176QqcpcnWcanVZZbaHb8B3h9" ] } ], "metadata": { "sequence": 2 }, "operation": "TRANSFER", "outputs": [ { "amount": "1", "condition": { "details": { "public_key": "3Af3fhhjU6d9WecEM9Uw5hfom9kNEwE7YuDWdqAUssqm", "type": "ed25519-sha-256" }, "uri": "ni:///sha-256;Ll1r0LzgHUvWB87yIrNFYo731MMUEypqvrbPATTbuD4?fpt=ed25519-sha-256&cost=131072" }, "public_keys": [ "3Af3fhhjU6d9WecEM9Uw5hfom9kNEwE7YuDWdqAUssqm" ] } ], "version": "1.0" }]
Response Headers: - Content-Type –
application/json
Status Codes: - 200 OK – A list of transactions containing an asset with ID
asset_id
was found and returned. - 400 Bad Request – The request wasn’t understood by the server, e.g. the
asset_id
querystring was not included in the request.
- operation (string) – (Optional) One of the two supported operations of a transaction:
-
POST
/api/v1/transactions
¶ Push a new transaction.
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. One would normally use a driver such as the BigchainDB Python Driver to build a valid transaction.
Example request:
POST /api/v1/transactions/ HTTP/1.1 Host: example.com Content-Type: application/json { "asset": { "data": { "msg": "Hello BigchainDB!" } }, "id": "8b20dbe164badd5ca0611b0e233aef9acce609fbca20f787fc7d926f300d0102", "inputs": [ { "fulfillment": "pGSAIDE5i63cn4X8T8N1sZ2mGkJD5lNRnBM4PZgI_zvzbr-cgUCGvCc2HO2uB4IKix6INRzGIM10r7VsKFMPM9cT7uVJ1xFLOJ9bn6UioepBMLIrrwTlk2CkTolIPonf7BnzriQL", "fulfills": null, "owners_before": [ "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD" ] } ], "metadata": { "sequence": 0 }, "operation": "CREATE", "outputs": [ { "amount": "1", "condition": { "details": { "public_key": "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD", "type": "ed25519-sha-256" }, "uri": "ni:///sha-256;PNYwdxaRaNw60N6LDFzOWO97b8tJeragczakL8PrAPc?fpt=ed25519-sha-256&cost=131072" }, "public_keys": [ "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD" ] } ], "version": "1.0" }
Example response:
HTTP/1.1 202 Accepted Location: ../statuses?transaction_id=8b20dbe164badd5ca0611b0e233aef9acce609fbca20f787fc7d926f300d0102 Content-Type: application/json { "asset": { "data": { "msg": "Hello BigchainDB!" } }, "id": "8b20dbe164badd5ca0611b0e233aef9acce609fbca20f787fc7d926f300d0102", "inputs": [ { "fulfillment": "pGSAIDE5i63cn4X8T8N1sZ2mGkJD5lNRnBM4PZgI_zvzbr-cgUCGvCc2HO2uB4IKix6INRzGIM10r7VsKFMPM9cT7uVJ1xFLOJ9bn6UioepBMLIrrwTlk2CkTolIPonf7BnzriQL", "fulfills": null, "owners_before": [ "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD" ] } ], "metadata": { "sequence": 0 }, "operation": "CREATE", "outputs": [ { "amount": "1", "condition": { "details": { "public_key": "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD", "type": "ed25519-sha-256" }, "uri": "ni:///sha-256;PNYwdxaRaNw60N6LDFzOWO97b8tJeragczakL8PrAPc?fpt=ed25519-sha-256&cost=131072" }, "public_keys": [ "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD" ] } ], "version": "1.0" }
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 status monitor provided in theLocation
header or listen to server’s WebSocket Event Stream API.Response Headers: - Content-Type –
application/json
- Location – Relative link to a status monitor for the submitted transaction.
Status Codes: - 202 Accepted – The pushed transaction was accepted in the
BACKLOG
, but the processing has not been completed. - 400 Bad Request – The transaction was malformed and not accepted in the
BACKLOG
.
- Content-Type –
Transaction Outputs¶
The /api/v1/outputs
endpoint returns transactions outputs filtered by a
given public key, and optionally filtered to only include either spent or
unspent outputs.
-
GET
/api/v1/outputs
¶ Get transaction outputs by public key. The
public_key
parameter must be a base58 encoded ed25519 public key associated with transaction output ownership.Returns a list of transaction outputs.
Parameters: - 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. - spent – 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
and unspent) associated with the
public_key
.
- public_key – Base58 encoded public key associated with output
ownership. This parameter is mandatory and without it
the endpoint will return a
-
GET
/api/v1/outputs?public_key={public_key}
¶ - Return all outputs, both spent and unspent, for the
public_key
.Example request:
GET /api/v1/outputs?public_key=1AAAbbb...ccc HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "output_index": 0, "transaction_id": "2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e" }, { "output_index": 1, "transaction_id": "2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e" } ]
Status Codes: - 200 OK – A list of outputs were found and returned in the body of the response.
- 400 Bad Request – The request wasn’t understood by the server, e.g. the
public_key
querystring was not included in the request.
-
GET
/api/v1/outputs?public_key={public_key}&spent=true
¶ - Return all spent outputs for
public_key
.Example request:
GET /api/v1/outputs?public_key=1AAAbbb...ccc&spent=true HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "output_index": 0, "transaction_id": "2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e" } ]
Status Codes: - 200 OK – A list of outputs were found and returned in the body of the response.
- 400 Bad Request – The request wasn’t understood by the server, e.g. the
public_key
querystring was not included in the request.
-
GET
/api/v1/outputs?public_key={public_key}&spent=false
¶ - Return all unspent outputs for
public_key
.Example request:
GET /api/v1/outputs?public_key=1AAAbbb...ccc&spent=false HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "output_index": 1, "transaction_id": "2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e" } ]
Status Codes: - 200 OK – A list of outputs were found and returned in the body of the response.
- 400 Bad Request – The request wasn’t understood by the server, e.g. the
public_key
querystring was not included in the request.
Statuses¶
-
GET
/api/v1/statuses
¶ Get the status of an asynchronously written transaction or block by their id.
Query Parameters: - transaction_id (string) – transaction ID
- block_id (string) – block ID
Note
Exactly one of the
transaction_id
orblock_id
query parameters must be used together with this endpoint (see below for getting transaction statuses and block statuses).
-
GET
/api/v1/statuses?transaction_id={transaction_id}
¶ Get the status of a transaction.
The possible status values are
undecided
,valid
orbacklog
. If a transaction in neither of those states is found, a404 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.Example request:
GET /statuses?transaction_id=8b20dbe164badd5ca0611b0e233aef9acce609fbca20f787fc7d926f300d0102 HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "valid" }
Response Headers: - Content-Type –
application/json
Status Codes: - 200 OK – A transaction with that ID was found.
- 404 Not Found – A transaction with that ID was not found.
- Content-Type –
-
GET
/api/v1/statuses?block_id={block_id}
¶ Get the status of a block.
The possible status values are
undecided
,valid
orinvalid
.Example request:
GET /api/v1/statuses?block_id=a5986a6b10b59b40138451aa2941577f5b3c051d49f416f1230d34ed5e09da01 HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "valid" }
Response Headers: - Content-Type –
application/json
Status Codes: - 200 OK – A block with that ID was found.
- 404 Not Found – A block with that ID was not found.
- Content-Type –
Assets¶
-
GET
/api/v1/assets
¶ Return all the assets that match a given text search.
Query Parameters: - text search (string) – Text search string to query.
- limit (int) – (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.
-
GET
/api/v1/assets?search={text_search}
¶ Return all assets that match a given text search. The
id
of the asset is the sameid
of the 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.The results are sorted by text score. For more information about the behavior of text search see MongoDB text search behavior
Example request:
GET /api/v1/assets/?search=bigchaindb HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-type: application/json [ { "data": {"msg": "Hello BigchainDB 1!"}, "id": "51ce82a14ca274d43e4992bbce41f6fdeb755f846e48e710a3bbb3b0cf8e4204" }, { "data": {"msg": "Hello BigchainDB 2!"}, "id": "b4e9005fa494d20e503d916fa87b74fe61c079afccd6e084260674159795ee31" }, { "data": {"msg": "Hello BigchainDB 3!"}, "id": "fa6bcb6a8fdea3dc2a860fcdc0e0c63c9cf5b25da8b02a4db4fb6a2d36d27791" } ]
Response Headers: - Content-Type –
application/json
Status Codes: - 200 OK – The query was executed successfully.
- 400 Bad Request – The query was not executed successfully. Returned if the text string is empty or the server does not support text search.
- Content-Type –
-
GET
/api/v1/assets?search={text_search}&limit={n_documents}
¶ Return at most
n
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.The results are sorted by text score. For more information about the behavior of text search see MongoDB text search behavior
Example request:
GET /api/v1/assets/?search=bigchaindb&limit=2 HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-type: application/json [ { "data": {"msg": "Hello BigchainDB 1!"}, "id": "51ce82a14ca274d43e4992bbce41f6fdeb755f846e48e710a3bbb3b0cf8e4204" }, { "data": {"msg": "Hello BigchainDB 2!"}, "id": "b4e9005fa494d20e503d916fa87b74fe61c079afccd6e084260674159795ee31" }, ]
Response Headers: - Content-Type –
application/json
Status Codes: - 200 OK – The query was executed successfully.
- 400 Bad Request – The query was not executed successfully. Returned if the text string is empty or the server does not support text search.
- Content-Type –
Advanced Usage¶
The following endpoints are more advanced and meant for debugging and transparency purposes.
More precisely, the blocks endpoint 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 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¶
-
GET
/api/v1/blocks/{block_id}
¶ Get the block with the ID
block_id
. Any blocks, be theyVALID
,UNDECIDED
orINVALID
will be returned. To check a block’s status independently, use the Statuses endpoint. To check the votes on a block, have a look at the votes endpoint.Parameters: - block_id (hex string) – block ID
Example request:
GET /api/v1/blocks/a5986a6b10b59b40138451aa2941577f5b3c051d49f416f1230d34ed5e09da01 HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "block": { "node_pubkey": "DngBurxfeNVKZWCEcDnLj1eMPAS7focUZTE5FndFGuHT", "timestamp": "1510581035", "transactions": [ { "asset": { "data": { "msg": "Hello BigchainDB!" } }, "id": "8b20dbe164badd5ca0611b0e233aef9acce609fbca20f787fc7d926f300d0102", "inputs": [ { "fulfillment": "pGSAIDE5i63cn4X8T8N1sZ2mGkJD5lNRnBM4PZgI_zvzbr-cgUCGvCc2HO2uB4IKix6INRzGIM10r7VsKFMPM9cT7uVJ1xFLOJ9bn6UioepBMLIrrwTlk2CkTolIPonf7BnzriQL", "fulfills": null, "owners_before": [ "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD" ] } ], "metadata": { "sequence": 0 }, "operation": "CREATE", "outputs": [ { "amount": "1", "condition": { "details": { "public_key": "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD", "type": "ed25519-sha-256" }, "uri": "ni:///sha-256;PNYwdxaRaNw60N6LDFzOWO97b8tJeragczakL8PrAPc?fpt=ed25519-sha-256&cost=131072" }, "public_keys": [ "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD" ] } ], "version": "1.0" } ], "voters": [ "DngBurxfeNVKZWCEcDnLj1eMPAS7focUZTE5FndFGuHT" ] }, "id": "a5986a6b10b59b40138451aa2941577f5b3c051d49f416f1230d34ed5e09da01", "signature": "53wxrEQDYk1dXzmvNSytbCfmNVnPqPkDQaTnAe8Jf43s6ssejPxezkCvUnGTnduNUmaLjhaan1iRLi3peu6s5DzA" }
Response Headers: - Content-Type –
application/json
Status Codes: - 200 OK – A block with that ID was found.
- 400 Bad Request – The request wasn’t understood by the server, e.g. just requesting
/blocks
without theblock_id
. - 404 Not Found – A block with that ID was not found.
-
GET
/api/v1/blocks
¶ The unfiltered
/blocks
endpoint without any query parameters returns a 400 status code. The list endpoint should be filtered with atransaction_id
query parameter, see the/blocks?transaction_id={transaction_id}&status={UNDECIDED|VALID|INVALID}
endpoint.Example request:
GET /api/v1/blocks HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 400 Bad Request
Status Codes: - 400 Bad Request – The request wasn’t understood by the server, e.g. just requesting
/blocks
without theblock_id
.
- 400 Bad Request – The request wasn’t understood by the server, e.g. just requesting
-
GET
/api/v1/blocks?transaction_id={transaction_id}&status={UNDECIDED|VALID|INVALID}
¶ Retrieve a list of
block_id
with their corresponding status that contain a transaction with the IDtransaction_id
.Any blocks, be they
UNDECIDED
,VALID
orINVALID
will be returned if no status filter is provided.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 Parameters: - transaction_id (string) – transaction ID (required)
- status (string) – Filter blocks by their status. One of
VALID
,UNDECIDED
orINVALID
.
Example request:
GET /api/v1/blocks?transaction_id=8b20dbe164badd5ca0611b0e233aef9acce609fbca20f787fc7d926f300d0102 HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ "e2e49acbe85adf9cbdf85cc21682a47f02cb6fe403fc99f5dd1e4a9549e4ad15", "a5986a6b10b59b40138451aa2941577f5b3c051d49f416f1230d34ed5e09da01" ]
Response Headers: - Content-Type –
application/json
Status Codes: - 200 OK – A list of blocks containing a transaction with ID
transaction_id
was found and returned. - 400 Bad Request – The request wasn’t understood by the server, e.g. just requesting
/blocks
, without definingtransaction_id
.
Votes¶
-
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:- Check if the vote’s
node_pubkey
is allowed to vote. - Verify the vote’s signature against the vote’s body (
vote.vote
) andnode_pubkey
.
Query Parameters: - block_id (string) – The block ID to filter the votes.
Example request:
GET /api/v1/votes?block_id=a5986a6b10b59b40138451aa2941577f5b3c051d49f416f1230d34ed5e09da01 HTTP/1.1 Host: example.com
Example response:
HTTP/1.1 200 OK Content-Type: application/json [{ "node_pubkey": "DngBurxfeNVKZWCEcDnLj1eMPAS7focUZTE5FndFGuHT", "signature": "646Ca8AVJsAiAYFXVKdZN9yLHMwQvHFGGmioJm6piLmby8ahSR8Mb4M78fvg8nphQ4jFtqaRNVNZpLDWmBqm2TE4", "vote": { "invalid_reason": null, "is_block_valid": true, "previous_block": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "timestamp": "1510581035", "voting_for_block": "a5986a6b10b59b40138451aa2941577f5b3c051d49f416f1230d34ed5e09da01" } }]
Response Headers: - Content-Type –
application/json
Status Codes: - 200 OK – A list of votes voting for a block with ID
block_id
was found and returned. - 400 Bad Request – The request wasn’t understood by the server, e.g. just requesting
/votes
, without definingblock_id
.
- Check if the vote’s
Determining the API Root URL¶
When you start BigchainDB Server using bigchaindb start
,
an HTTP API is exposed at some address. The default is:
http://localhost:9984/api/v1/
It’s bound to localhost
,
so you can access it from the same machine,
but it won’t be directly accessible from the outside world.
(The outside world could connect via a SOCKS proxy or whatnot.)
The documentation about BigchainDB Server Configuration Settings
has a section about how to set server.bind
so as to make
the HTTP API publicly accessible.
If the API endpoint is publicly accessible, 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). It’s determined by AWS, Azure, Rackspace, or whoever is hosting the machine.
- The DNS hostname (like example.com) is determined by DNS records, such as an “A Record” associating example.com with 12.34.56.78
- 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 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.)