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 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 an acceptable 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. 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 Parameter	Type	Description	Default
`pageSize`	integer `[10..100]`	Selects the number of entries to return. Example: `http://localhost:3000/blocks?pageSize=100` returns 100 entries per `page`	`10`
`pageNumber`	integer `>=1`	Filters by page number. Example: `http://localhost:3000/blocks?page=2` returns page 2	`1`
`offset`	string (id)	Identifies the entry at which to start pagination. Example: `http://localhost:3000/blocks?id=EE94FD819A1B30D6C5D1C03`.
`order`	string `{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`
`orderBy`	string	Chooses 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
    }
  }