@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
}
}