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 Problemtypen mit Hinweisen zu Wiederholungsversuchen zurückgibt, führen automatisierte Clients weniger Wiederholungen nicht wiederholbarer Anfragen und weniger doppelte Schreibvorgänge aus als bei rein textbasierten Fehlermeldungen; 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.
-
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.
-
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: Aufbau der Anfrage, Fehler, erneute Versuche und Versionsfixierung
Der dokumentierte Vertrag, den ein Agent braucht, um Jev ohne Chat-Schicht aufzurufen: POST /v1/systemone mit einem Bearer-Schlüssel, einem Zustand, einem Modellnamen und einer Zuordnung typisierter Fragen; Antworten unter denselben Schlüsseln wie die Fragen plus einem usage-Block; 401, 422, 429 und 529 mit exponentiellem Backoff; Aliasse, die sich verschieben, und versionierte Kennungen, die es nicht tun; SDK-Standardwerte für erneute Versuche und der Agenten-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.
-
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.
-
Konsistente API-Fehlerantworten mit Problem Details
RFC 9457 definiert eine JSON-Form für HTTP-Fehlerantworten (type, title, status, detail, instance), damit Clients Fehler einheitlich behandeln können; jede konsistente Hülle mit stabilen maschinenlesbaren Codes erreicht dasselbe Ziel.
-
MCP-Werkzeuge gestalten, die Agenten sicher benutzen können
Werkzeuge nach dem Model Context Protocol brauchen einen engen Zweck, typisierte Eingabe- und Ausgabeschemata, wahrheitsgemässe Annotationen (nur lesend, destruktiv), begrenzte Ergebnisse und Fehler, die die Ursache nennen; Beschreibungen gehören in den Code, nicht in Inhalte, die Nutzende bearbeiten können. Die Spezifikation verlangt zudem, dass Clients Annotationen als nicht vertrauenswürdig behandeln und ein Mensch Aufrufe ablehnen kann.
-
Datums- und Zeitformate in APIs: ISO 8601 und RFC 3339
Zeitstempel als RFC-3339-Strings mit explizitem Offset austauschen, Datumsangaben als YYYY-MM-DD, Zeitdauern als ISO-8601-Dauern oder reine Sekunden; nie als sprachraumabhängigen Text oder als mehrdeutige Zahlen.
Maschinenlesbar: JSON