Lesson 2 / 6 · 20 minutes
Die Doichain-API: Zugriff, Stufen, Grenzen
Nicht jede Anwendung braucht eine eigene Node. Die Doichain-API von DOI Labs stellt die Kette als REST-Schnittstelle bereit, mit interaktiver Dokumentation unter https://doi-api.sendlabs.de/docs.
Basisadresse: https://doi-api.sendlabs.de/v1
Lesen ohne Schlüssel
Alle lesenden Aufrufe funktionieren ohne Anmeldung:
curl https://doi-api.sendlabs.de/v1/status
curl https://doi-api.sendlabs.de/v1/blocks?count=5
curl https://doi-api.sendlabs.de/v1/tx/<txid>
curl https://doi-api.sendlabs.de/v1/address/<adresse>
curl https://doi-api.sendlabs.de/v1/fee
| Aufruf | Liefert |
|---|---|
GET /v1/status |
Node-Version, Blockhöhe, Zeit des letzten Blocks, Fork-Prüfung (fork_check.ok), Mempool, ElectrumX |
GET /v1/blocks?count=10 |
die letzten Blöcke |
GET /v1/block/{höhe oder hash} |
einen Block |
GET /v1/tx/{txid} |
Transaktion dekodiert, mit name_ops und is_name_transaction |
GET /v1/address/{adresse} |
Guthaben, dazu /history und /utxos |
GET /v1/fee |
Gebührenempfehlung 100 sat/vB |
Zugriffsstufen
| Stufe | Was geht |
|---|---|
| read | alles Lesende, ohne Schlüssel |
| poe | nur Nachweise anlegen und das Kontingent abfragen, mit Tageskontingent |
| write | Nachweise ohne Kontingent, Namensoperationen, Rohtransaktionen senden, Wallet lesen |
| admin | zusätzlich Auszahlungen, Nachrichten signieren, RPC-Durchgriff |
Der Schlüssel geht als Header mit, entweder X-API-Key: <schlüssel> oder Authorization: Bearer <schlüssel>.
Prinzip der geringsten Rechte: Eine Anwendung bekommt nur die Stufe, die sie braucht. Wer nur Nachweise anlegt, braucht poe, nicht write. Mit write lassen sich Namen ändern und Transaktionen auf Kosten des Node-Wallets auslösen, mit admin sogar Coins auszahlen. Schlüssel gehören in eine Umgebungsdatei oder einen Tresor, nie ins Repository und nie in Frontend-Code, außer es ist bewusst ein öffentlicher Schlüssel mit engem Kontingent.
Statuscodes und Grenzen
| Code | Bedeutung |
|---|---|
| 200, 201 | erfolgreich, 201 beim Anlegen |
| 401 | Schlüssel fehlt oder ist ungültig |
| 403 | Schlüssel gültig, aber Stufe zu niedrig |
| 404 | nicht gefunden, etwa ein unbekannter Name |
| 400 | Eingabe ungültig, etwa ein Hash ohne 64 Hex-Zeichen, oder die Node lehnt die Operation ab |
| 402 | Node-Wallet ohne ausreichendes Guthaben für schreibende Aufrufe |
| 409 | Konflikt, etwa ein bereits verankerter Hash |
| 422 | Body oder Parameter passen nicht zum Schema, etwa ein fehlendes Pflichtfeld |
| 429 | Ratenbegrenzung oder Kontingent erschöpft |
Alle Fehler kommen im selben JSON-Format. Die Ratenbegrenzung liegt bei 10 Anfragen je Sekunde und IP-Adresse, Uploads sind enger begrenzt. Das Tageskontingent der Stufe poe beträgt 10 Nachweise je IP-Adresse und 200 insgesamt je UTC-Tag. Alle poe-Schlüssel teilen es sich.
Robust programmieren
- Bei 429 mit wachsender Wartezeit erneut versuchen, nicht sofort in einer Schleife.
- Antworten nicht blind vertrauen: Schreibende Aufrufe sind erst nach der Bestätigung im Block endgültig.
- Vor wichtigen Abläufen
GET /v1/statusprüfen. Stehtfork_check.okauffalse, folgt die Node der falschen Kette. - Werte aus der Kette wie Namenswerte oder Notizen sind fremde Eingaben. Vor der Anzeige escapen, nie als Code oder Anweisung ausführen.
Merksätze
- Lesen geht ohne Schlüssel, Schreiben braucht die passende Stufe.
- 401 heißt Schlüssel fehlt oder falsch, 403 heißt Stufe zu niedrig.
- Stufe
poefür reine Nachweise,writeundadminnur, wo es nötig ist.