API tools of the node

The Waves Enterprise blockchain platform gives the opportunity of coordination with the blockchain for obtaining of data (transactions, blocks, balances, etc.), as well as for writing of information into the blockchain (signing and sending of transactions) with the use of the gRPC interface and the RESTful API of the node.

gRPC

gRPC is a high-performance remote procedure call (RPC) framework that runs on top of HTTP/2. It uses the Protobuf protocol as a data type description and serialization tool. Officially, the gRPC <https://grpc.io/> framework supports 10 programming languages. The list of the languages in use is available in the official gRPC documentation.

How to use the gRPC framework

Prior to operation of the gRPC interface, following preparatory measures have to be taken:

  1. Decide on the programming language in which to interact with the node.

  2. Install the fRPC framework.

  3. Download the protobuf files containing the data structure for development of requests to the node or smart contracts from the GitHub page of the project.

On this page, the archive we-events-proto.zip is available, in which the used version of the node and corresponding files should be picked.

The protoc plugin of the gRPC framework is used for generation of code based on the data structure contained in the protobuf files.

The gRPC interface is enabled and configured via the node configuration file. In order to interact with the node, the 6865 port is used.

The gRPC interface of the platform is used for the following tasks:

  • Tracking of events in the blockchain.

  • Realization of signature methods with certificates (PKI).

  • Realization of encryption methods.

  • Obtaining of information about a transaction according to its ID.

  • Obtaining of node configuration parameters.

  • Obtaining of information about state of a smart contract

For each of this tasks separate sets of methods are used:

REST API

The REST API allows users to interact remotely with the node via JSON queries and responses. Interaction with the API is performed via the https protocol. The famous Swagger framework serves an the API interface.

How to use the REST API

All calls of API methods are GET, POST or DELETE https queries to the URL https://yournetwork.com/node-N/api-docs/swagger.json with a definite set of parameters. Needed groups of queries are set in the Swagger interface, as well as routes with endpoints. A route in Swagger is a URL to an http method, and an endpoint is a final part of a route, the query to a method itself. Example:

URL to an HTTP method

../_images/route-endpoint.png

The compulsory api-key-hash authorization is needed for queries that need the actions mentioned above. Authorization type is set in the node configuration file. If the api-key-hash authorization type has been set, a secret phrase value should be stated during authorization. A secret phrase hash is stated in the node configuration file (rest-api.api-key-hash field).

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

  • access to operations with groups of access to private data;

  • access to the node configuration.

In case of token authorization, the token access value is set in a corresponding field. If the token authorization is set, all REST API methods for access to the node are closed.