HTTP API приложений

Что это такое

Интерфейс сети - это JSON-RPC. Всё на этих страницах - то, что приложение построило для себя и оставило доступным: индекс Postgres поверх спула логов секвенсера, процесс, держащий ключ, игровой цикл. Это удобно, это своё, и это не является источником истины.

Где они отвечают

Ни у одного из этих сервисов нет собственного имени хоста. Каждый - это монтирование /api/ на источнике какого-то фронтенда, что делает публичную базу фактом nginx, а не фактом сервиса: развёртывание, которое переносит сайт, переносит вместе с ним и его API, а путь внутри остаётся тем же. В стеке, который вы запускаете сами, те же сервисы отвечают на локальной петле, на порту, который называет страница каждого из них.

Аутентификация

Ни один из четырёх не требует аутентификации, и важно здесь то, что каждый из них может сделать без неё.

• Обозреватель, API DEX и аркада не требуют ничего. Они только на чтение и публичны. Обозреватель отвечает 405 на любой POST; API DEX не реализует никакого глагола, кроме GET.
• Кран тоже ничего не требует, и он пишет в сеть. Именно поэтому его квота строга и резервируется до того, как что-либо подписано.

Вызов из браузера

CORS настроен для каждого сервиса по-своему, и между собой они не согласованы, так что первое, что надо установить, - может ли страница с вашего источника вообще вызвать нужный вам сервис.

• API DEX не отправляет заголовка CORS и не имеет обработчика OPTIONS. fetch из браузера с другого источника отказывает наглухо, тогда как тот же запрос с сервера проходит, - это тот вид бага, который списывают на сеть. Проксируйте его или вызывайте с бэкенда.
• Обозреватель и кран держат списки разрешённых. Предварительный запрос с источника, которого в списке нет, получает отказ 403 - это по крайней мере внятный ответ.
• Аркада проверяет Origin при апгрейде и отказывает 403 до рукопожатия, так что сокет вовсе не открывается, вместо того чтобы открыться и замолчать.

Пределы и постраничность

Частоту запросов ограничивает только обозреватель. Остальные три опираются на ограничение сверху, квоту или потолок соединений.

Там, где постраничность есть, это limit и offset, а не курсор. Значит, список, растущий с головы, съезжает под вами между двумя страницами: уже увиденные строки появляются снова, а невиденные можно пропустить. Для всего, что должно быть полным, листайте по ключу, которым управляете вы, - по номеру блока, по хешу, - а не по смещению.

Соглашения

// The shape of a careful call against any of these: a timeout, a status check
// before the body, and a big-integer parse of anything that looks like money.
const res = await fetch(`${BASE}/pools`, { signal: AbortSignal.timeout(5000) });
if (!res.ok) throw new Error(`pools: ${res.status}`);          // never the message
const { pools } = await res.json();                              // an object, not an array
const reserve0 = BigInt(pools[0].reserve0);                      // a decimal string

Когда один из них лежит

Каждый из четырёх отказывает по-своему, и только один из этих отказов выглядит отказом снаружи.

• API DEX отвечает 503 index not ready, когда база данных недоступна или индексатор ни разу не отработал, так что таблиц не существует. Это честный случай. Нечестный - индексатор, который ОСТАНОВИЛСЯ: все маршруты продолжают отвечать тем состоянием, до которого он дошёл, и говорит об этом только lagBlocks на /health.
• Обозреватель продолжает отдавать индекс, когда узел недоступен, а те части ответа, которым нужно живое чтение - баланс, запись сервиса имён, ожидающий баланс маршрутизатора комиссий, - возвращаются нулевыми или отсутствуют, а не дают ошибку. Следить надо за полем indexLag на /stats.
• Кран отвечает 502, когда узел не отвечает, и ничего не было подписано. 503 означает, что у него кончились средства или что drip сделал revert.
• /ready аркады отвечает 503, когда её сокет к узлу упал или когда последний мини-блок, который она ПРИМЕНИЛА, старше пяти секунд. Измерение прибытия вместо этого позволяло заклинившему процессу отвечать 200, когда ничего не двигалось.

Что задокументировано в другом месте

• The node. Chain state, transactions, logs and subscriptions are JSON-RPC and are documented in this reference's own RPC pages, not here.
• Contracts. What the pools, the faucet and the games actually do on chain - their functions, their events and their revert reasons - is the contract reference.
• Prices. Several answers here carry a dollar figure or a price snapshot. Those fields come from a layer this page does not own; read its own reference for what the number means, how old it is and when it is absent.