REST Gateway

Catapult REST combines HTTP and WebSockets to perform read and write actions on the blockchain.

Http requests

The REST Gateway uses the port 3000 and accepts both HTTP GET, PUT and POST requests.

Assuming that Catapult REST is running locally, HTTP GET requests can be executed from a browser and have the form:

http://localhost:3000/<path-to-API-request>

Conversely, HTTP PUT and POST requests have the same structure but use JSON structures in the request body. This kind of request cannot usually be executed from within the browser unless you use a plugin which enables you to do it.

Endpoints

Refer to the next documentation to get the list of available endpoints.

To check the compatibility between the API specification and the REST Gateway implementation, see Product Compatibility Matrix.

Response codes

Symbol uses conventional HTTP response codes to indicate the success or failure of an API request.

  • Codes in the 2xx range indicate success.
  • Codes in the 4xx range indicate an error occurred with the information provided by the user.
  • Codes in the 5xx range indicate an error with the node.
HTTP Status Code Summary
Error Code Response Description
200 OK Everything worked as expected.
202 Accepted The request has been accepted, but the processing has not been completed.
400 InvalidContent The provided argument was not of an acceptable type of input.
404 ResourceNotFound The requested resource does not exist.
409 InvalidArgument The required arguments were missing or unacceptable for the request.
500 InternalServiceError An error occurred within the REST Gateway.
503 ServiceUnavailable Either API node or database service is unavailable or unreachable from the REST Gateway.

WebSockets

To get live updates when an event occurs on the blockchain, Catapult REST publishes WebSockets. Client applications can open a WebSocket connection and get a unique identifier. With this identifier, applications qualify to subscribe to the available channels instead of constantly polling the API for updates. When an event occurs in a channel, the REST Gateway sends a notification to every subscribed client in real-time.

WebSocket URIs share the same host and port as the HTTP requests URIs, but use the ws:// protocol:

ws://localhost:3000/ws

Channels

block

The block channel notifies for every subscribed client every time there is a new harvested block. The messages returned contain information about the blocks.

Request body

{
    "uid": "{uid}",
    "subscribe": "block"
}

Response format

confirmedAdded/{address}

The confirmedAdded channel notifies when a transaction related to an address is included in a block. The messages returned contain information about the confirmed transactions.

Request body

{
    "uid": "{uid}",
    "subscribe": "confirmedAdded/{address}"
}

Response format

unconfirmedAdded/{address}

The unconfirmedAdded channel notifies when a transaction related to an address gets the unconfirmed state, waiting to be included in a block. The messages returned contain information about unconfirmed transactions.

Possible scenarios when this channel notifies are: the transaction is announced to the network via PUT /transaction HTTP endpoint or an AggregateBondedTransaction has all required cosigners and change its state from partial to unconfirmed.

Request body

{
    "uid": "{uid}",
    "subscribe": "unconfirmedAdded/{address}"
}

Response format

unconfirmedRemoved/{address}

The unconfirmedRemoved channel notifies when a transaction related to an address had the unconfirmed state, but not anymore. The messages returned contain the transactions hashes.

Possible scenarios when this channel notifies are: the transaction now is confirmed, or the deadline has been reached, and it was not included in a block.

Request body

{
    "uid":"{uid}",
    "subscribe":"unconfirmedRemoved/{address}"
}

Response format

  • Hash

partialAdded/{address}

The partialAdded channel notifies when an AggregateBondedTransaction related to an address reaches the partial state, waiting to have all required cosigners. The messages returned contain information about the transactions.

Request body

{
    "uid": "{uid}",
    "subscribe": "partialAdded/{address}"
}

Response format

partialRemoved/{address}

The partialRemoved channel notifies when a transaction related to an address had the partial state, but is not anymore. The messages returned contain the transactions hashes.

Possible scenarios when this channel notifies are: the transaction now is unconfirmed, or the deadline has been reached, and it was not included in a block.

Request body

{
    "uid": "{uid}",
    "subscribe": "partialRemoved/{address}"
}

Response format

  • Hash

cosignature/{address}

The cosignature channel notifies when a cosignature signed transaction related to an address is added to an AggregateBondedTransaction with the partial state. The messages returned contain the cosignature signed transaction.

Request body

{
    "uid": "{uid}",
    "subscribe": "cosignature/{address}"
}

Response format

status/{address}

The status channel notifies when a transaction related to an address rises an error. The messages returned contain the error messages and the transaction hashes.

Request body

{
    "uid": "{uid}",
    "subscribe": "status/{address}"
}

Response format