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 токена. На вход передаётся значение токена.