Thema: api-design
-
HTTP-Statuscodes richtig verwenden: die erste Verzweigung des Clients
Clients, Caches und Agenten entscheiden allein am Statuscode über Wiederholen, Neuladen oder Aufgeben: 201/204 für Erfolg mit und ohne Körper, 401 gegen 403 für fehlende Anmeldung gegen fehlende Berechtigung, 409/412/428 für Konflikte und Vorbedingungen, 429 und 503 mit Retry-After für «später». Ein 200 mit Fehlerobjekt täuscht alle.
-
Maschinenlesbare Fehlertypen verringern schädliche Wiederholungsversuche durch Agenten
Hypothese: Wenn eine API stabile Problem-Typen mit Wiederholungshinweisen zurückgibt, führen automatisierte Clients weniger Wiederholungsversuche nicht wiederholbarer Anfragen und weniger doppelte Schreibvorgänge aus als bei Fehlermeldungen in reinem Fliesstext; ein vorgeschlagener Vergleich.
-
Als Client zurückweichen: Retry-After, RateLimit-Header und Budgets pro Host
Wie ein Agent auf 429- und 503-Antworten sowie auf informative Rate-Limit-Header reagieren sollte: Retry-After exakt befolgen, sonst exponentiell mit Jitter zurückweichen, die Felder RateLimit und RateLimit-Policy lesen, sofern ein Server sie sendet, um dem Limit zuvorzukommen, ein Budget pro Host und pro Schlüssel führen und einen nicht-idempotenten Schreibvorgang nie ohne Idempotenzschlüssel wiederholen.
-
Rate-Limits gestalten, die den Dienst schützen und den Client informieren
Nach der verifizierbaren Identität begrenzen (Konto, Netzwerkpräfix), atomare Zähler in festen oder gleitenden Fenstern verwenden, mit 429 und Retry-After antworten, getrennte Budgets für Lese-, Schreib- und Registrierungsvorgänge führen und die geltenden Limits veröffentlichen.
-
Stripe-API: Paginierung und Idempotency-Keys (starting_after, has_more und das 24-Stunden-Fenster)
Die List-Endpunkte der Stripe-API v1 paginieren über die sich gegenseitig ausschliessenden Cursor-Parameter starting_after und ending_before (limit 1–100, Standard 10) sowie das Flag has_more; Auto-Pagination-Helfer der Client-Bibliotheken durchlaufen alle Seiten. POST-Requests können einen Idempotency-Key tragen, dessen gespeichertes Ergebnis Stripe etwa 24 Stunden lang erneut ausliefert, danach können Keys gelöscht werden. Requests, die ein Rate Limit auslösen, erhalten 429 mit dem Header Stripe-Rate-Limited-Reason.
-
Konsistente Benennung und Schreibweise von JSON-Feldern
Eine einzige Schreibkonvention für Eigenschaftsnamen wählen und sie überall anwenden: Googles JSON-Style-Guide und ProtoJSON verwenden lowerCamelCase, viele APIs verwenden snake_case. Über die Schreibweise hinaus Namen bedeutungsvoll halten, Enums als Strings, Zeitstempel als RFC-3339-Strings und 64-Bit-Ganzzahlen als Strings.
-
Standard Webhooks im Vergleich: Shopifys HMAC-Header und GitLabs Shared-Secret-Token
Die Standard-Webhooks-Spezifikation definiert die Header webhook-id, webhook-timestamp und webhook-signature, ein mit whsec_ präfixiertes Base64-Secret, dessen dekodierte Bytes den HMAC-Schlüssel bilden, sowie eine Signatur v1,<base64> über "{id}.{timestamp}.{payload}". GitLabs Signing Tokens (GitLab 19.0, allgemein verfügbar ab 19.1) setzen genau das um. Shopify sendet stattdessen einen Base64-HMAC des rohen Bodys in X-Shopify-Hmac-SHA256, und GitLabs älterer X-Gitlab-Token ist ein schlichtes Shared Secret und gar kein HMAC.
-
JSON mit JSON Schema validieren
JSON Schema beschreibt die erlaubte Form eines Dokuments (Typen, Pflichtfelder, Aufzählungen, Formate, Grenzwerte) und lässt jede Sprache Eingaben vor der Verarbeitung validieren; additionalProperties sollte explizit gesetzt werden.
-
Idempotente Operationen und sichere Wiederholungen entwerfen
Eine Operation ist idempotent, wenn ihre mehrfache Ausführung dieselbe Wirkung hat wie eine einzelne; RFC 9110 legt das für HTTP-Methoden fest, und ein Idempotency-Key-Header überträgt die Eigenschaft auf POST. Schlüssel samt Fingerabdruck und Ergebnis speichern, Konflikte mit 409 und 422 melden, Schlüssel nach dokumentierter Frist löschen.
-
Die TypeSafe-API aus einem Agenten heraus aufrufen: Anfragestruktur, Fehler, Wiederholungsversuche und Versionsfixierung
Der dokumentierte Vertrag, den ein Agent braucht, um Jev ohne Chat-Schicht aufzurufen: POST /v1/systemone mit einem Bearer-Key, einem State, einem Modellnamen und einer Map typisierter Fragen; Antworten mit denselben Schlüsseln wie die Fragen plus einem Usage-Block; 401, 422, 429 und 529 mit exponentiellem Backoff; Aliasse, die sich verschieben, und versionierte IDs, die es nicht tun; SDK-Standardwerte für Wiederholungsversuche und der Agent-Skill für Coding-Agenten.
-
Dry-Run-Modi für Agentenhandlungen: den Plan vor der Änderung zeigen
Jedem Werkzeug, das Zustand ändert, einen Modus geben, der den konkreten Plan (welche Objekte, welche Felder, wie viele) berechnet und zurückgibt, ohne ihn anzuwenden, den Plan serverseitig validieren, wo das System dies erlaubt, verlangen, dass der Plan vor dem echten Aufruf erzeugt und geprüft wird, und das tatsächliche Ergebnis anschliessend mit ihm vergleichen.
-
Der Link-Header und Link-Relationstypen
RFC 8288 erlaubt jeder HTTP-Antwort, getypte Links in einem Link-Header zu tragen: <ziel>; rel="relation" plus optionale Parameter anchor, hreflang, type, title und media. Relationsnamen stammen aus der IANA-Registry (next, prev, canonical, alternate, describedby, preload) oder sind absolute URIs für private Erweiterungen. So verweisen Nicht-HTML-Antworten auf ihre Nachbarn, und so teilt 103 Early Hints einem Browser mit, was früh abzurufen ist.
-
HEAD und OPTIONS: was sie beantworten und wofür Clients sie nutzen
HEAD ist GET ohne Rumpf: gleicher Status und gleiche Header (Content-Length und Vary dürfen fehlen), cachefähig, eingesetzt für Link-Prüfungen, Grössenabfragen und Aktualitätsprüfungen. OPTIONS fragt, welche Kommunikationsoptionen eine Ressource oder der gesamte Server (OPTIONS *) unterstützt, wird typischerweise mit Allow beantwortet, ist nicht cachefähig und trägt CORS-Preflights mit Access-Control-Request-Method.
-
Slack-Request-Signaturen prüfen: X-Slack-Signature, 5-Minuten-Replay-Fenster und die 3-Sekunden-Regel
Slack signiert Requests als v0=<Hex-HMAC-SHA256> des Strings "v0:{timestamp}:{raw body}" im Header X-Slack-Signature, zusammen mit X-Slack-Request-Timestamp. Slacks eigenes Beispiel weist Requests ab, deren Zeitstempel mehr als fünf Minuten von der lokalen Zeit abweicht. Slash Commands und interaktive Payloads müssen zusätzlich innerhalb von drei Sekunden bestätigt werden, bevor aufwendige Verarbeitung beginnt.
-
Ein SDK über einer HTTP-API entwerfen
Ein SDK sollte den korrekten Aufruf zum einfachen Aufruf machen: typisierte Modelle, ein Client-Objekt, das die Konfiguration hält, einheitliche Fehler, Wiederholungen mit Idempotenzschlüsseln, Iteratoren für Pagination und Hilfsmittel für lang laufende Operationen – wo möglich aus der API-Beschreibung generiert und nur dort von Hand geschrieben, wo die Generierung die Absicht nicht ausdrücken kann.
-
Ausgehende Webhooks entwerfen, denen Empfänger vertrauen können
Jede Zustellung mit einem HMAC über Body und Zeitstempel signieren, mindestens einmal mit Wiederholungen und idempotenten Ereignis-IDs zustellen, Payloads klein halten mit einem Link zum Abrufen der Details, und Empfängern die Prüfung ermöglichen, ohne Geheimnisse in URLs zu platzieren.
-
Bulk-Endpunkte und die Meldung teilweiser Fehlschläge
Ein Bulk-Endpunkt gelingt oder scheitert entweder als Ganzes, oder er meldet die Ergebnisse pro Element; ein einzelnes 200 kann einen Teilerfolg nicht ausdrücken, daher pro Endpunkt ein Verhalten festlegen, Fehlschläge nach Position indexieren, die Batchgrösse begrenzen und Autorisierung sowie Ratenbegrenzung pro Element anwenden.
-
HTTP-Statuscodes bewusst wählen
Statuscodes sind das Erste, wonach ein Client verzweigt: 200/201/204 für Erfolg, 304 für unverändert, 400/422 für fehlerhafte Eingaben, 401/403 für Anmeldedaten gegenüber Berechtigung, 404 für nicht vorhanden, 409/412/428 für Konflikte und Vorbedingungen, 429/503 für später.
-
Agent-zu-Agent-Protokolle im Überblick: A2A-Agent-Cards, Tasks und wo MCP hineinpasst
Was das A2A-Protokoll (Version 1.0.0, Linux Foundation) zwischen unabhängigen Agents standardisiert: eine veröffentlichte Agent Card unter /.well-known/agent-card.json mit Fähigkeiten, Skills, Endpunkt und Sicherheitsschemata; Tasks mit einem Lebenszyklus aus submitted, working, input-required, auth-required, completed, failed, canceled und rejected; Nachrichten und Artefakte, die aus Parts bestehen; JSON-RPC-, gRPC- und REST-Bindings; sowie die eigene Darstellung der Spezifikation, wie sie MCP ergänzt.
-
Accept-Language-Aushandlung und ihre Grenzen
Accept-Language trägt eine gewichtete Liste von Sprachbereichen (da, en-gb;q=0.8, en;q=0.7); der Server gleicht sie mit den vorhandenen Sprachen mittels Filterung oder Lookup nach RFC 4647 ab, antwortet mit Content-Language und Vary: Accept-Language und muss sinnvoll zurückfallen, wenn der Header fehlt (Googlebot sendet keinen) oder falsch liegt (eine Geräte-Locale ist nicht die Wahl der lesenden Person). Als ersten Anhaltspunkt verwenden, nicht als einzigen Auswahlmechanismus.
Maschinenlesbar: JSON