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

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

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

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

URL к HTTP-методу

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

доступ к keystore ноды (например, метод sign);
доступ к операциям с группами доступа к приватным данным;
доступ к конфигурации ноды.

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

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

gRPC-интерфейс предназначен для отслеживания определённых групп событий, происходящих в блокчейне. События формируются в стримы, которые приходят в gRPC-интерфейс по подписке. Включение gRPC-интерфейса и его настройка выполняются через конфигурационный файл ноды, которая будет прослушиваться интерфейсом.

Включите и настройте gRPC-интерфейс в соответствующих настройках конфигурационного файла ноды. Для инициализации подписки отправьте запрос SubscribeRequest(startFrom, transactionTypeFilter), где используются следующие параметры:

startFrom - момент начала стрима, возможные варианты:
- CurrentEvent - получение событий от ноды в реальном времени по мере поступления,
- GenesisBlock - получение событий с самого первого блока,
- BlockSignature - получение событий после указанного блока.
transactionTypeFilter - фильтрация транзакций, которые будут приходить внутри событий, возможные варианты:
- Any - все транзакции,
- Filter - в событиях будут содержаться только те типы транзакций, которые будут указаны в списке внутри фильтра,
- FilterNot - в событиях не будут содержаться только те типы транзакций, которые будут указаны в списке внутри фильтра.

Вместе с запросом отправляются метаданные для авторизации, включающие токен или фразу api-key. Поддерживаются оба варианта авторизации - по api-key и токену.

После оформления успешной подписки нода начнет стриминг следующих событий:

MicroBlockAppended - смайненный микроблок с параметрами:
- transactions - полные тела транзакций из микроблока.
BlockAppended - смайненный блок с параметрами:
- signature - подпись блока,
- reference - подпись предыдущего блока,
- tx ids - список ID транзакций из блока,
- miner address - адрес майнера,
- height - высота блока.
RollbackCompleted - событие отката блокчейна с параметрами:
- return to block signature - подпись блока, до которого необходимо откатиться,
- rollback tx ids - список ID транзакций, которые будут удалены из блокчейна.
AppendedBlockHistory - если в запросе на подписку не был выбран параметр CurrentEvent, клиент будет получать данный тип событий до тех пор, пока не дойдет до текущей высоты блокчейна и тогда переключится на остальные события:
- signature - подпись блока,
- reference - подпись предыдущего блока,
- transactions - полные тела транзакций из блока,
- miner address - адрес майнера,
- height - высота блока.
ErrorEvent - событие информирует о возникновении ошибки. Типы ошибок:
- GenericError - общая или неизвестная ошибка с текстом сообщения,
- MissingRequiredRequestField - незаполненное обязательное поле из SubscribeRequest,
- BlockSignatureNotFoundError - подпись запрошенного блока из SubscribeRequest отсутствует в блокчейне,
- MissingAuthorizationMetadata - отсутствие авторизационных метаданных при отправке SubscribeRequest,
- InvalidApiKey - неверная фраза api-key, в случае авторизации c api-key,
- InvalidToken - неверный токен, в случае авторизации по OAuth.

Методы авторизации¶

В зависимости от метода авторизации указываются разные значения для получения доступа к REST API ноды.

OAuth2 Bearer (apiKey) - значение access токена.
ApiKey or PrivacyApiKey (apiKey) - значение api-key-hash как для общего доступа к REST API ноды, так и для доступа к методам privacy.

Авторизация по `api-key-hash`¶

Генерация значения api-key-hash выполняется при конфигурации ноды. Также получить значение поля rest-api.api-key-hash можно при помощи метода /utils/hash/secure REST API ноды. Для подписания запросов ключем из keystore ноды в поле password запроса POST /transaction/sign требуется указания пароля доступа к keystore.

Пример запроса:

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'

Авторизация по токену¶

Если используется сервис авторизации, для доступа к ноде и другим сервисам клиент получает пару токенов - refresh и access. Токены можно получить через REST API сервиса авторизации.

Для регистрации пользователя используется метод POST /v1/user. На вход передаются следующие параметры:

login - логин пользователя (электронный адрес пользователя). В качестве логина используется электронный адрес пользователя.
password - пароль для доступа к аккаунту.
locale - выбор языка, на котором пользователю будет предоставляться информация на почту. Возможные варианты en и ru.
source - тип пользователя. Возможные варианты license и voting.

Только после регистрации пользователь получает токены авторизации.

Для получения и обновления токенов авторизации используются следующие методы:

POST /v1/auth/login - получение токена авторизации с использованием логина и пароля. Этот метод предназначен для авторизации пользователей.
POST /v1/auth/token - получение refresh и access токенов авторизации для сервисов и приложений. Метод не требует параметров и в ответ на вызов присылает значения токенов. Метод может быть использовать только администратором сервиса авторизации.
POST /v1/auth/refresh - обновление refresh токена. На вход передаётся значение токена.