Публичные API

Anon публикует небольшой набор публичных HTTP API. Это JSON-эндпоинты только для чтения на https://api.anon.inc, которые может вызывать кто угодно: кошельки, дашборды, страницы статуса и скрипты. API-ключ и аккаунт не нужны, а браузер на любом сайте может их читать.

Бета: все API на этой странице находятся в бета-версии. Поля, значения и форма ответа могут измениться без предупреждения. Пишите клиент так, чтобы он игнорировал неизвестные поля и значения, и читайте раздел о статусе беты и журнал изменений на странице каждого API.

Список API

API	Эндпоинт	Что возвращает	Кеш	Схема
Доступность RAILGUN	`GET /api/v1/railgun/liveness`	Отвечают ли прямо сейчас сервисы Railgun, от которых зависит Anon, и не отстают ли они, по каждой сети.	15 с в браузерах, 30 с в общих кешах	JSON Schema
История доступности RAILGUN	`GET /api/v1/railgun/liveness/history`	Последние 14 дней того же отчёта в 5-минутных интервалах с доступностью за 24 часа, 7 и 14 дней.	60 с в браузерах, 120 с в общих кешах	JSON Schema

Чтобы решить, что верно сейчас, используйте живой эндпоинт, а для графиков и страниц статуса — историю. Оба показывают то, что видит собственный монитор Anon. Это не официальный статус Railgun и никогда не сигнал «безопасно проводить транзакции».

curl -i https://api.anon.inc/api/v1/railgun/liveness
curl -i https://api.anon.inc/api/v1/railgun/liveness/history

Что общего у всех публичных API

Параметр	Значение
Базовый URL	`https://api.anon.inc`
Аутентификация	Нет
Методы	`GET` и `HEAD`. `OPTIONS` отвечает на предварительные запросы CORS. Любой другой метод получает `405`.
Параметры запроса	Нет. Любая строка запроса игнорируется.
Формат	JSON (`application/json; charset=utf-8`) с полем `schemaVersion`
Статус	Бета, без срока уведомления и без SLA

CORS. Каждый ответ содержит Access-Control-Allow-Origin: * и Access-Control-Expose-Headers: ETag и никогда не содержит Access-Control-Allow-Credentials. Обычному fetch предварительный запрос не нужен.
Кеширование. Каждый 200 содержит Cache-Control и ETag. Отправьте ETag обратно в If-None-Match, и неизменившийся ответ придёт как 304 без тела. CDN хранит отдельную копию для каждого значения заголовка запроса Origin.
Ошибки. Ветвитесь по коду состояния HTTP, а не по тексту сообщения. Ошибка самого API — это {"error": "<message>"} с Cache-Control: no-store. 503 означает, что данные сейчас недоступны: повторяйте запрос с нарастающими паузами.
Ограничение частоты. Если с одного IP приходит больше примерно 120 запросов в минуту, CDN примерно 60 секунд отвечает 429 (ошибка Cloudflare 1015). Попадания в кеш тоже учитываются. В браузере у этого 429 нет заголовка CORS, поэтому fetch завершается сетевой ошибкой.
JSON Schema намеренно нестрогие. Они описывают сегодняшние ответы и не являются обещанием.

Добросовестное использование

Соблюдайте Cache-Control и используйте ETag, чтобы неизменившийся ответ обходился 304.
Запрашивайте данные, когда пользователь открывает экран, которому они нужны, а не по таймеру.
Серверы, которые опрашивают API, должны отправлять описательный User-Agent, например my-wallet/1.4 (+https://example.com/contact).
Если вы обслуживаете много пользователей, получайте данные своим сервером и кешируйте их там.
При 429 и 5xx делайте паузу и продолжайте показывать последний корректный ответ.

Другие маршруты на api.anon.inc

Публичные API — это только эндпоинты, перечисленные на этой странице. Остальные маршруты на api.anon.inc обслуживают собственные приложения и сайты Anon. Некоторые из них отвечают без ключа, но они не документированы для сторонних клиентов и могут в любой момент измениться, переехать или стать недоступными. Не стройте на них свои решения.