REST API

The Waves Enterprise blockchain platform provides an opportunity to interact with blockchain both in terms of receiving data (transactions, blocks, balances, etc.) and in terms of writing information to blockchain (signing and sending transactions) via RESTful API of the node. REST API allows users to interact remotely with the node using requests and responses in JSON format. HTTPS protocol is using to work with API and as an interface it is utilized the Swagger framework.

How to use REST API

All API methods are including GET, POST or DELETE HTTPS requests to URL https://yournetwork.com/node-N/api-docs/swagger.json using the set of parameters. The requests groups with routes and endpoints are selected in the Swagger interface. The route is the URL of the HTTP method, and the endpoint is the final part of the route, this is the access to the method. Example:

URL to the HTTP-method

../_images/route-endpoint.png

For requests requiring the following actions, mandatory authorization by api-key-hash is required. The authorization type is specified in the node configuration file. If api-key-hash authorization type is selected, it is necessary to specify the value of the secret phrase, the hash of which is wrote in the node configuration file (rest-api.api-key-hash field).

  • access to the node keystore (for example, sign method);

  • access to operations with confidential data access groups;

  • access to the node configuration.

When authorized by token, the value of access token is specified in the corresponding field. If token authorization is selected, then all REST API methods for node access are closed.

Authorization methods

Depending on the authorization method, different values are specified to get the access to the node REST API.

../_images/authTypes.png
  • OAuth2 Bearer (apiKey) - an access token value.

  • ApiKey or PrivacyApiKey (apiKey) - api-key-hash value for both access to the node REST API and privacy methods.

api-key-hash authorization

The api-key-hash generation is happening during the node configuration. The value of the field rest-api.api-key-hash can be also generated using the /utils/hash/secure method of node REST API. It is required to specify the access password to the keystore in the password field of the POST /transaction/sign request for signing requests by the node keystore key.

Sample query:

curl -X POST
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'X-API-Key: 1' -d '1' 'http://2.testnet-pos.com:6862/transactions/calculateFee'

Token authorization

If the authorization service is used, the client receives a pair of tokens - refresh and access - for the node and other services access. Tokens can be obtained via the authorization service REST API.