REST Gateway

@dhealth/rest combines HTTP and WebSockets to perform read and write actions on the blockchain.

Http requests

The REST Gateway uses port 3000 for HTTP and port 3001 for HTTPS, and it accepts GET, PUT and POST requests.

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

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

PUT and POST requests have the same query format but use JSON structures in the request body.
This kind of request cannot usually be executed from within the browser unless you use an extension.

Response codes

dHealth 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.
Error CodeResponseDescription
200OKEverything worked as expected.
202AcceptedThe request has been accepted, but the processing has not been completed.
400InvalidContentThe provided argument was not an acceptable input.
404ResourceNotFoundThe requested resource does not exist.
409InvalidArgumentThe required arguments were missing or unacceptable for the request.
500InternalServiceErrorAn error occurred within the REST Gateway.
503ServiceUnavailableEither API node or database service is unavailable or unreachable from the REST Gateway. Check the /node/health endpoint.

Pagination

When a query returns more than one result, the REST Gateway paginates the responses by default.
The query parameters can be customized to advance through the pages and filter the returned content.

Each pageable endpoint defines its own set of filters.
However, the following table shows the query params present in every searchable endpoint:

Query ParameterTypeDescriptionDefault
pageSizeinteger [10..100]Selects the number of entries to return. Example: http://localhost:3000/blocks?pageSize=100 returns 100 entries per page10
pageNumberinteger >=1Filters by page number. Example: http://localhost:3000/blocks?page=2 returns page 21
offsetstring (id)Identifies the entry at which to start pagination. Example: http://localhost:3000/blocks?id=EE94FD819A1B30D6C5D1C03.
orderstring {asc, desc}Sorts the responses in ascending or descending order based on the collection property set on the parameter orderBy. If the request does not specify orderBy, REST returns the collection ordered by id. Example: http://localhost:3000/blocks?order=asc returns the block entries in ascending order.desc
orderBystringChooses the parameter to sort by. By default, all the collections are sortable by id, but the collection could define additional properties.

Multiple query parameters can be combined in the same call.
For example, http://localhost:3000/blocks?pageSize=100&id=EE94FD819A1B30D6C5D1C03 will return 100 block entries per page starting with block id EE94FD819A1B30D6C5D1C03.

The responses also include meta-information about the pagination total number of entries, current page number, and the total number of pages.
Here is an example response meta-information of the pagination:

  {
    "data": [
      {}
    ],
    "pagination": {
      "pageNumber": 0,
      "pageSize": 0,
      "totalEntries": 0,
      "totalPages": 0
    }
  }