Anwendungs-APIs

Was diese Dienste sind

Die Schnittstelle der Chain ist JSON-RPC. Alles auf diesen Seiten ist etwas, das eine Anwendung für sich selbst gebaut und dann erreichbar gelassen hat: ein Postgres-Index über den Log-Spool des Sequencers, ein Prozess, der einen Schlüssel hält, eine Spielschleife. Sie sind bequem, sie sind hauseigen, und sie sind nicht maßgeblich.

Wo sie antworten

Nicht einer dieser Dienste hat einen eigenen Hostnamen. Jeder ist ein /api/-Einhängepunkt auf der Herkunft eines Frontends, was die öffentliche Basis zu einer Tatsache von nginx macht statt zu einer des Dienstes: Ein Deployment, das eine Website verschiebt, verschiebt ihre API mit, und der Pfad darin bleibt derselbe. Auf einem Stack, den Sie selbst betreiben, antworten dieselben Dienste stattdessen auf Loopback, auf dem Port, den die Seite des jeweiligen Dienstes nennt.

Authentifizierung

Keiner der vier verlangt eine Authentifizierung, und was zählt, ist, was jeder von ihnen ohne eine tun kann.

• Der Explorer, die DEX-API und die Arcade nehmen keine. Sie sind nur lesend und öffentlich. Der Explorer antwortet jedem POST mit 405; die DEX-API implementiert kein Verb außer GET.
• Der Faucet nimmt ebenfalls keine, und er schreibt auf die Chain. Das ist der ganze Grund, warum seine Quote streng ist und reserviert wird, bevor irgendetwas signiert wird.

Einen davon aus einem Browser aufrufen

CORS wird pro Dienst gesetzt, und sie sind sich uneinig; als Erstes ist also zu klären, ob eine Seite auf Ihrer Herkunft den gewünschten Dienst überhaupt aufrufen kann.

• Die DEX-API sendet keinen CORS-Header und hat keinen OPTIONS-Handler. Ein herkunftsübergreifendes fetch aus einem Browser scheitert rundheraus, während dieselbe Anfrage von einem Server gelingt, und das ist die Art von Fehler, die dem Netzwerk angelastet wird. Legen Sie einen Proxy davor, oder rufen Sie sie aus einem Backend auf.
• Der Explorer und der Faucet führen Allowlists. Ein Preflight von einer Herkunft, die nicht auf der Liste steht, wird mit 403 abgelehnt, was immerhin eine klare Antwort ist.
• Die Arcade prüft die Origin beim Upgrade und lehnt vor dem Handshake mit 403 ab, der Socket öffnet also gar nicht erst, statt zu öffnen und dann zu schweigen.

Grenzen und Blättern

Nur der Explorer begrenzt die Anfragerate. Die drei anderen verlassen sich stattdessen auf eine Kappung, eine Quote oder eine Verbindungsobergrenze.

Wo es Blättern gibt, ist es limit und offset, kein Cursor. Das heißt, dass eine Liste, die am Kopf wächst, zwischen zwei Seiten unter Ihnen verrutscht: Zeilen, die Sie schon gesehen haben, tauchen wieder auf, und Zeilen, die Sie noch nicht gesehen haben, können übersprungen werden. Für alles, was vollständig sein muss, blättern Sie über einen Schlüssel, den Sie kontrollieren - eine Blocknummer, einen Hash - statt über einen Offset.

Konventionen

// 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

Wenn einer ausfällt

Jeder der vier scheitert anders, und nur einer dieser Fehlschläge sieht von außen wie ein Fehlschlag aus.

• Die DEX-API antwortet 503 index not ready, wenn die Datenbank nicht erreichbar ist oder der Indexer nie gelaufen ist, die Tabellen also nicht existieren. Das ist der ehrliche Fall. Der unehrliche ist ein Indexer, der ANGEHALTEN hat: Jede Route antwortet weiter mit dem Stand, den sie erreicht hat, und nur lagBlocks auf /health sagt es.
• Der Explorer liefert den Index weiter aus, wenn der Node nicht erreichbar ist, und die Teile einer Antwort, die einen Live-Lesezugriff brauchen - ein Guthaben, ein Eintrag im Namensdienst, das ausstehende Guthaben des Gebühren-Routers -, kommen als null oder gar nicht zurück, statt einen Fehler zu melden. Das Feld indexLag auf /stats ist die Zahl, die es zu beobachten gilt.
• Der Faucet antwortet 502, wenn der Node nicht antwortet, und es wurde nichts signiert. Eine 503 heißt, ihm fehlen die Mittel, oder der Drip hat revertet.
• Die /ready der Arcade antwortet 503, wenn ihr Socket zum Node unten ist, oder wenn der letzte Mini-Block, den sie ANGEWANDT hat, älter als fünf Sekunden ist. Stattdessen die Ankunft zu messen ließ einen verklemmten Prozess mit 200 antworten, während sich nichts bewegte.

Was anderswo dokumentiert ist

• 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.