Node API tools

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 and gRPC interface. 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. The gRPC interface is designed for listening to collections of events from a node.

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.

How to use the gRPC interface

The gRPC interface is designed to track certain groups of events that occur in the blockchain. Events are generated in streams that are sent to the gRPC interface by subscription. Enabling the gRPC interface and configuring is performing via node configuration file, which will be listened by the interface.

Enable and configure the gRPC interface in the appropriate settings configuration file:. To initialize a subscription, send the Subscribe Request(start From, transaction Type Filter), where the following parameters are used:

  • startFrom - a moment when the stream starts, possible options:

    • CurrentEvent - getting events from a node in real time as they are received,

    • GenesisBlock - getting events from the very first block,

    • BlockSignature - getting events after the specified block.

  • transactionTypeFilter - filtering transactions that will be received within events, possible options:

    • Any - all transactions,

    • Filter - events will contain only the transaction types that are specified in the list inside the filter,

    • FilterNot - events will not contain only the transaction types that are listed in the list inside the filter.

Authorization metadata is sent along with the request, including the token or the api-key phrase. Both api-key and token authorization options are supported.

After completing a successful subscription, the node will start streaming the following events:

  • MicroBlockAppended - a mained microblock with parameters:

    • transactions - full transactions bodies from a microblock.

  • BlockAppended - a mained microblock with parameters:

    • signature - a block signature,

    • reference - a previous block signature,

    • tx ids - list of transaction IDs from the block,

    • miner address - a mainer address,

    • height - a blocks height.

  • RollbackCompleted - a blockchain rollback event with parameters:

    • return to block signature - a block signature to roll back to,

    • rollback tx ids - a transactions ID list to be deleted from the blockchain.

  • AppendedBlockHistory - if the CurrentEvent parameter was not selected in the subscription request, the client will receive this type of event until it reaches the current height of the blockchain and then switches to other events:

    • signature - a block signature,

    • reference - a previous block signature,

    • transactions - full transactions bodies from a block.

    • miner address - a mainer address,

    • height - a blocks height.

  • ErrorEvent - the event informs you that an error has occurred. Types of errors:

    • GenericError - a general or unknown error with message text,

    • MissingRequiredRequestField - a blank required field from SubscribeRequest,

    • BlockSignatureNotFoundError - the signature of the requested block from SubscribeRequest is not present in the blockchain,

    • MissingAuthorizationMetadata - no authorization metadata when sending SubscribeRequest,

    • InvalidApiKey - invalid api key phrase, in case of authorization with the api key,

    • InvalidToken - invalid token for OAuth authorization.

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.

To register a user, use the POST /v1/user method. The following parameters are passed as input:

  • login - a user’s login (a user’s email address). The user’s email address is used as the username.

  • password - a password to the account access.

  • locale - select the language in which the user will receive information via email. Possible options are en and ru.

  • source - a user type. Possible options are license and voting.

Only after registration the user receives authorization tokens.

The following methods are used to get and update authorization tokens:

  1. POST ​/v1​/auth​/login - getting an authorization token using your username and password. This method is intended for users authorization.

  2. POST ​/v1​/auth​/token - getting refresh and access authorization tokens for services and applications. The method does not require parameters and sends token values in response to the call. This method can only be used by the administrator of the authorization service.

  3. POST ​/v1​/auth​/refresh - refresh token update. The token value is passed to the input.