API-инструменты ноды

Блокчейн-платформа Waves Enterprise предоставляет возможность взаимодействия с блокчейном как в части получения данных (транзакции, блоки, балансы и др.), так и в части записи информации в блокчейн (подписание и отправка транзакций) при помощи gRPC-интерфейса и RESTful API ноды.

gRPC

gRPC — это высокопроизводительный фреймворк для вызов удаленных процедур (RPC), который работает поверх HTTP/2. В качестве инструмента описания типов данных и сериализации используется протокол Protobuf. Официально фреймворк gRPC поддерживает 10 языков программирования. Список используемых языков доступен в официальной документации gRPC.

Как использовать фреймворк gRPC

Перед использованием gRPC-интерфейса необходимо выполнить следующие подготовительные действия:

  1. Определиться с языком программирования, на котором будет осуществляться взаимодействие с нодой.

  2. Установить фреймворк gRPC.

  3. Скачать protobuf файлы, содержащие структуру данных для разработки обращений к ноде или смарт-котрактов, со страницы проекта в GitHub.

На этой странице доступен архив we-events-proto.zip, в котором необходимо выбрать используемую версию ноды и соответствующие файлы.

Для генерации кода на базе структуры данных из protobuf файлов используется плагин плагин protoc фреймворка gRPC.

Включение gRPC-интерфейса и его настройка выполняются через конфигурационный файл ноды. Для взаимодействия с нодой предусмотрен порт 6865.

gRPC-интерфейс платформы предназначен для выполнения следующих задач:

  • Отслеживание определенных групп событий, происходящих в блокчейне.

  • Реализация методов подписи с сертификатом (PKI).

  • Реализация методов шифрования.

  • Получение информации о транзакции по ее ID.

  • Получение параметров конфигурации ноды.

  • Получение информации о состоянии смарт-контракта

Для каждой из этих задач предусмотрены отдельные наборы методов:

REST API

REST API позволяет пользователям удалённо взаимодействовать с нодой через запросы и ответы в формате JSON. Работа с API происходит по протоколу https. Удобным интерфейсом к API служит известный фреймворк Swagger.

Как использовать REST API

Все вызовы методов API — это GET, POST или DELETE https-запросы к URL https://yournetwork.com/node-N/api-docs/swagger.json с набором параметров. В интерфейсе Swagger выбираются нужные группы запросов и далее маршруты с точками доступа. Маршрут в Swagger это URL к http-методу, а точка доступа (endpoint) - конечная часть маршрута, само обращение к методу. Пример:

URL к HTTP-методу

../_images/route-endpoint.png

Для запросов, требующих нижеперечисленных действий, необходима обязательная авторизация по api-key-hash. Тип авторизации устанавливается в конфигурационном файле ноды. Если выбран тип авторизации по api-key-hash, то при авторизации необходимо указывать значение секретной фразы, hash которой указан в конфигурационном файле ноды (поле rest-api.api-key-hash).

  • доступ к keystore ноды (например, метод sign);

  • доступ к операциям с группами доступа к приватным данным;

  • доступ к конфигурации ноды.

При авторизации по токену в соответствующем поле указывается значение access токена. Если выбрана авторизация по токену, в таком случае закрыты все методы REST API для доступа к ноде.