REST API Specification¶
This document is a complete specification of Sawtooth Lake’s REST API, built from the official OpenAPI formatted YAML specification, which can be found on the Sawtooth Lake Github.
Note
This specification has not been fully implemented, and at this point should be considered a roadmap rather than a reference for usage. Until complete, many of the endpoints may not work, or may behave differently than documented.
-
POST
/batches
¶ Sends a BatchList to the validator
Accepts a protobuf formatted BatchList as an octet-stream binary file and submits it to the validator to be committed.
If the wait parameter is set in the url, the API will try to wait to respond until all batches have been committed to the blockchain, returning a 201 response with a link to the committed batches.
If wait is set to a positive integer, the API will timeout and return after that time in seconds has elapsed. If set to any non-integer value other than false (including simply ?wait), the API may still timeout, but will use its own settings (usually 300s). After timing out, a 200 is returned with a data object that include the statuses of each batch (COMMITTED, INVALID, PENDING, or UNKNOWN), and a link to a /batch_status endpoint for further polling.
If wait is not set, or is set to false, the API will return immediately with a status of 202. There will be no data object, only a link to a /batch_status endpoint to be polled to check the status of submitted batches.
Query Parameters: - callback (string) – Callback url
- wait (integer) – A time in seconds to wait for commit
Status Codes: - 200 OK – Batches submitted, but not all committed
- 201 Created – Successfully committed all Batches in BatchList
- 202 Accepted – Successfully submitted BatchList for validation
- 400 Bad Request – Request was malformed
- 500 Internal Server Error – Something went wrong within the validator
- 503 Service Unavailable – API is unable to reach the validator
-
GET
/batches
¶ Fetches a list of batches
Fetches a paginated list of batches from the validator.
Query Parameters: - head (string) – Index or id of head block
- count (integer) – Number of items to return
- min (string) – Id or index to start paging (inclusive)
- max (string) – Id or index to end paging (inclusive)
- sort (string) – Field to sort a list by, - reverses order
- fields (string) – Comma separated list of fields to include in response, defaults to all
- omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes: - 200 OK – Successfully retrieved batches
- 400 Bad Request – Request was malformed
- 500 Internal Server Error – Something went wrong within the validator
- 503 Service Unavailable – API is unable to reach the validator
-
GET
/batches/{batch_id}
¶ Fetches a particular batch
Parameters: - batch_id (string) – Batch id
Query Parameters: - fields (string) – Comma separated list of fields to include in response, defaults to all
- omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes: - 200 OK – Successfully retrieved batch
- 400 Bad Request – Request was malformed
- 404 Not Found – Address or id did not match any resource
- 500 Internal Server Error – Something went wrong within the validator
- 503 Service Unavailable – API is unable to reach the validator
-
GET
/batch_status
¶ Fetches the committed statuses for a set of batches
Fetches an object with a status for each batch requested. The keys of the data object will be the ids of the batch(es), while the values will be a string status with the values ‘COMMITTED’, ‘INVALID’, ‘PENDING’, or ‘UNKNOWN’.
The batch(es) you want to check can be specified using the id filter parameter. If a wait time is specified in the url, the API will wait to respond until all batches are committed, or the time in seconds has elapsed. If the value of wait is not set (i.e. ?wait&id=...), or it is set to any non-integer value other than false, the wait time will be just shy of the api’s specified timeout (usually 300).
Note that as this route does not return a full resource, and the response body will _not_ include the head or paging properties.
Query Parameters: - id (string) – A comma seperated list of batch ids
- wait (integer) – A time in seconds to wait for commit
Status Codes: - 200 OK – Successfully retrieved statuses
- 400 Bad Request – Request was malformed
- 500 Internal Server Error – Something went wrong within the validator
- 503 Service Unavailable – API is unable to reach the validator
-
POST
/batch_status
¶ Fetches the committed statuses for a set of batches
Identical to GET /batch_status, but takes ids of batches as a JSON formatted POST body rather than a query parameter. This allows for many more batches to be checked and should be used for more than 15 ids.
Note that since query information is not encoded in the URL, no link will be returned with this query.
Query Parameters: - wait (integer) – A time in seconds to wait for commit
Status Codes: - 200 OK – Successfully retrieved statuses
- 400 Bad Request – Request was malformed
- 500 Internal Server Error – Something went wrong within the validator
- 503 Service Unavailable – API is unable to reach the validator
-
GET
/state
¶ Fetches the data for the current state
Fetches a paginated list of leaves for the current state, or relative to a particular head block. Using the address filter parameter, will narrow the list to any leaves that have an address beginning with the characters specified.
Query Parameters: - head (string) – Index or id of head block
- address (string) – A partial address to filter leaves by
- count (integer) – Number of items to return
- min (string) – Id or index to start paging (inclusive)
- max (string) – Id or index to end paging (inclusive)
- sort (string) – Field to sort a list by, - reverses order
- fields (string) – Comma separated list of fields to include in response, defaults to all
- omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes: - 200 OK – Successfully retrieved state data
- 400 Bad Request – Request was malformed
- 500 Internal Server Error – Something went wrong within the validator
- 503 Service Unavailable – API is unable to reach the validator
-
GET
/state/{address}
¶ Fetches a particular leaf from the current state
Parameters: - address (string) – Radix address of a leaf, or prefix for leaves
Query Parameters: - head (string) – Index or id of head block
- fields (string) – Comma separated list of fields to include in response, defaults to all
- omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes: - 200 OK – Successfully fetched leaves
- 400 Bad Request – Request was malformed
- 404 Not Found – Address or id did not match any resource
- 500 Internal Server Error – Something went wrong within the validator
- 503 Service Unavailable – API is unable to reach the validator
-
GET
/blocks
¶ Fetches a list of blocks
Fetches a paginated list of blocks from the validator.
Query Parameters: - head (string) – Index or id of head block
- count (integer) – Number of items to return
- min (string) – Id or index to start paging (inclusive)
- max (string) – Id or index to end paging (inclusive)
- sort (string) – Field to sort a list by, - reverses order
- fields (string) – Comma separated list of fields to include in response, defaults to all
- omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes: - 200 OK – Successfully retrieved blocks
- 400 Bad Request – Request was malformed
- 500 Internal Server Error – Something went wrong within the validator
- 503 Service Unavailable – API is unable to reach the validator
-
GET
/blocks/{block_id}
¶ Fetches a particlar block
Parameters: - block_id (string) – Block id
Query Parameters: - fields (string) – Comma separated list of fields to include in response, defaults to all
- omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes: - 200 OK – Successfully retrieved block
- 400 Bad Request – Request was malformed
- 404 Not Found – Address or id did not match any resource
- 500 Internal Server Error – Something went wrong within the validator
- 503 Service Unavailable – API is unable to reach the validator
-
GET
/transactions
¶ Fetches a list of transactions
Fetches a paginated list of transactions from the validator.
Query Parameters: - head (string) – Index or id of head block
- count (integer) – Number of items to return
- min (string) – Id or index to start paging (inclusive)
- max (string) – Id or index to end paging (inclusive)
- sort (string) – Field to sort a list by, - reverses order
- fields (string) – Comma separated list of fields to include in response, defaults to all
- omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes: - 200 OK – Successfully retrieved transactions
- 400 Bad Request – Request was malformed
- 500 Internal Server Error – Something went wrong within the validator
- 503 Service Unavailable – API is unable to reach the validator
-
GET
/transactions/{transaction_id}
¶ Fetches a particular transaction
Parameters: - transaction_id (string) – Trainsaction id
Query Parameters: - fields (string) – Comma separated list of fields to include in response, defaults to all
- omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes: - 200 OK – Successfully retrieved transaction
- 400 Bad Request – Request was malformed
- 404 Not Found – Address or id did not match any resource
- 500 Internal Server Error – Something went wrong within the validator
- 503 Service Unavailable – API is unable to reach the validator
-
GET
/stats/validator
¶ Fetches metrics for the validator processing blocks
Fetches a snapshot of metrics relating to this validator’s processing of blocks. These metrics are raw totals of various validator processes, and any processing of the data will depend on the clients consuming it. These totals are further broken down by types of Transaction Processor.
Query Parameters: - fields (string) – Comma separated list of fields to include in response, defaults to all
- omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes: - 200 OK – Successfully fetched validator stats
- 400 Bad Request – Request was malformed
- 500 Internal Server Error – Something went wrong within the validator
- 503 Service Unavailable – API is unable to reach the validator
-
GET
/stats/gossip
¶ Fetches metrics for inter-validator communication
Fetches a snapshot of metrics relating to this validator’s communication with peer validators. These metrics represent raw totals, and any processing of the data will depend on the clients consuming it. These totals are further broken down by the ids of peers.
Query Parameters: - fields (string) – Comma separated list of fields to include in response, defaults to all
- omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes: - 200 OK – Successfully fetched gossip stats
- 400 Bad Request – Request was malformed
- 500 Internal Server Error – Something went wrong within the validator
- 503 Service Unavailable – API is unable to reach the validator
-
GET
/status/config
¶ Fetches the current configuration of the validator
Query Parameters: - fields (string) – Comma separated list of fields to include in response, defaults to all
- omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes: - 200 OK – Successfully fetched validator config
- 400 Bad Request – Request was malformed
- 500 Internal Server Error – Something went wrong within the validator
- 503 Service Unavailable – API is unable to reach the validator
-
GET
/status/system
¶ Fetches the current status of the system the validator is on
Query Parameters: - fields (string) – Comma separated list of fields to include in response, defaults to all
- omit (string) – Comma separated list of fields to omit from response, defaults to none
Status Codes: - 200 OK – Successfully fetched system status
- 400 Bad Request – Request was malformed
- 500 Internal Server Error – Something went wrong within the validator
- 503 Service Unavailable – API is unable to reach the validator