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:

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:

If you want to do more sophisticated queries
than those provided by the BigchainDB HTTP API,
then one option is to connect to MongoDB directly (if possible)
and do whatever queries MongoDB allows.
For more about that option, see
the page about querying BigchainDB.

This endpoint is used to send a transaction to a BigchainDB network.
The transaction is put in the body of the request.

Query Parameters:

mode (string) – (Optional) One of the three supported modes to send a transaction: async, sync, commit. The default is async.

Once the posted transaction arrives at a BigchainDB node,
that node will check to see if the transaction is valid.
If it’s invalid, the node will return an HTTP 400 (error).
Otherwise, the node will send the transaction to Tendermint (in the same node) using the
Tendermint broadcast API.

The meaning of the mode query parameter is inherited from the mode parameter in
Tendermint’s broadcast API.
mode=async means the HTTP response will come back immediately,
before Tendermint asks BigchainDB Server to check the validity of the transaction (a second time).
mode=sync means the HTTP response will come back
after Tendermint gets a response from BigchainDB Server
regarding the validity of the transaction.
mode=commit means the HTTP response will come back once the transaction
is in a committed block.

Note

In the async and sync modes, after a successful HTTP response is returned, the transaction may still be rejected later on. All the transactions are recorded internally by Tendermint in WAL (Write-Ahead Log) before the HTTP response is returned. Nevertheless, the following should be noted:

Transactions in WAL including the failed ones are not exposed in any of the BigchainDB or Tendermint APIs.

Transactions are never fetched from WAL. WAL is never replayed.

A critical failure (e.g. the system is out of disk space) may occur preventing transactions from being stored in WAL, even when the HTTP response indicates a success.

If a transaction fails the validation because it conflicts with the other transactions of the same block, Tendermint includes it into its block, but BigchainDB does not store these transactions and does not offer any information about them in the APIs.

Note

The posted transaction should be valid.
The relevant
BigchainDB Transactions 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.

Note

A client can subscribe to the
WebSocket Event Stream API
to listen for committed transactions.

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.

Note

If you want to do more sophisticated queries
than those provided by the BigchainDB HTTP API,
then one option is to connect to MongoDB directly (if possible)
and do whatever queries MongoDB allows.
For more about that option, see
the page about querying BigchainDB.

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 – (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
and unspent) associated with the public_key.

If you want to do more sophisticated queries
than those provided by the BigchainDB HTTP API,
then one option is to connect to MongoDB directly (if possible)
and do whatever queries MongoDB allows.
For more about that option, see
the page about querying BigchainDB.

If you want to do more sophisticated queries
than those provided by the BigchainDB HTTP API,
then one option is to connect to MongoDB directly (if possible)
and do whatever queries MongoDB allows.
For more about that option, see
the page about querying BigchainDB.

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

In case no block was found, an empty list and an HTTP status code
200OK is returned, as the request was still successful.

When you start BigchainDB Server using bigchaindbstart,
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.)