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.
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-samples/index-response.http
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-samples/api-index-response.http
The /api/v1/outputs endpoint returns transactions outputs filtered by a given public key, and optionally filtered to only include outputs that have not already been spent.
Example request:
http-samples/get-statuses-tx-request.http
Example response:
http-samples/get-statuses-tx-valid-response.http
- resheader Content-Type
application/json- resheader Location
Once the transaction has been persisted, this header will link to the actual resource.
- statuscode 200
A transaction with that ID was found.
- statuscode 404
A transaction with that ID was not found.
Example request:
http-samples/get-statuses-block-request.http
Example response:
http-samples/get-statuses-block-invalid-response.http
Example response:
http-samples/get-statuses-block-valid-response.http
- resheader Content-Type
application/json- resheader Location
Once the block has been persisted, this header will link to the actual resource.
- statuscode 200
A block with that ID was found.
- statuscode 404
A block with that ID was not found.
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 tx_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 tx_id, one can now simply inspect the votes that happened at a specific time on that block.
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.bindsetting 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.)