HTTP und
API-Verträge

HTTP ist ein Anwendungsprotokoll für den Austausch von Nachrichten. Ein Client sendet einen Request an einen Server. Der Request besteht aus Methode, URL, Headern und optional einem Body. Der Server antwortet mit Statuscode, Headern und optional einem Body. Diese Teile haben unterschiedliche Aufgaben: Die URL identifiziert das Ziel, ein Header transportiert Kontext wie Medientyp oder Berechtigung und der Body enthält die eigentlichen Nutzdaten.

REST ist ein Architekturstil. Eine REST-orientierte API stellt Ressourcen über stabile Adressen bereit und nutzt die Semantik von HTTP. GET liest, ohne den fachlichen Zustand zu verändern. POST stösst eine Verarbeitung an oder legt eine Ressource unter serverseitig bestimmter ID an. PUT ersetzt den Zustand einer bekannten Ressource und ist grundsätzlich idempotent. PATCH beschreibt eine Teiländerung; ob deren Wiederholung sicher ist, hängt vom Patch-Vertrag ab. DELETE entfernt die adressierte Ressource fachlich oder technisch.

„Idempotent“ bedeutet: Mehrfache identische Ausführung hat denselben beabsichtigten fachlichen Effekt wie eine Ausführung. Das garantiert nicht denselben Statuscode. Das erste DELETE kann mit 204 antworten, das zweite mit 404; die Ressource bleibt dennoch gelöscht. Diese Unterscheidung wird wichtig, sobald Timeouts und Wiederholungen auftreten.

Ein API-Vertrag beschreibt, worauf sich Anbieter und Konsumenten verlassen dürfen: Pfade, Methoden, Parameter, Header, Authentifizierung, Datenschemas, Statuscodes und Fehler. OpenAPI kann diesen Vertrag maschinenlesbar dokumentieren. JSON Schema beschreibt unter anderem Pflichtfelder, Datentypen, Wertebereiche, Formate und erlaubte zusätzliche Felder. Ein Beispiel zeigt nur einen möglichen Fall; ein Schema beschreibt die Menge erlaubter Fälle.

Die fachliche Bedeutung gehört ebenfalls zum Vertrag. Das Feld quantity: 3 ist syntaktisch eindeutig, aber ohne Einheit und Regel möglicherweise unklar. Darf die Menge null sein? Sind Dezimalwerte erlaubt? Bezieht sich ein Datum auf UTC oder die Zeitzone Europe/Zurich? Ist customerId eine Shop-ID oder eine ERP-ID? Gute Beschreibungen machen solche Annahmen sichtbar.

Verträge sollten möglichst rückwärtskompatibel wachsen. Ein optionales Feld lässt sich häufig hinzufügen, ohne alte Konsumenten zu brechen. Das Umbenennen oder Entfernen eines Pflichtfeldes ist dagegen eine brechende Änderung. Versionierung ist kein Ersatz für Planung: Zu viele parallele Versionen erhöhen Test- und Betriebskosten.

Statuscodes geben eine erste Klasse des Ergebnisses an. 200 steht für eine erfolgreiche Antwort, 201 für eine neu angelegte Ressource, 202 für angenommene, aber noch nicht abgeschlossene Verarbeitung und 204 für Erfolg ohne Body. 400 signalisiert eine unbrauchbare Anfrage, 401 fehlende oder ungültige Anmeldung, 403 fehlende Berechtigung, 404 eine unbekannte Ressource, 409 einen Zustandskonflikt, 422 fachlich nicht verarbeitbare Daten und 429 eine überschrittene Begrenzung. Serverfehler liegen im Bereich 5xx.

Der Statuscode allein genügt für die Diagnose selten. Ein stabiles Fehlerobjekt sollte einen maschinenlesbaren Typ, einen verständlichen Titel, Detailinformationen, betroffene Felder und eine Correlation-ID enthalten. Interne Stacktraces, Datenbanknamen oder geheime Werte gehören nicht in eine öffentliche Antwort. Ein Konsument muss technische Fehler anders behandeln können als fachliche Ablehnungen.

Die Metapher: Eine API-Dokumentation ist wie eine Speisekarte: Sie nennt verfügbare Leistungen und erwartete Angaben. Der HTTP-Request ist der Bestellzettel, die Methode beschreibt die gewünschte Aktion und die Antwort bestätigt Annahme, Ergebnis oder Problem. Ein standardisiertes Fehlerobjekt entspricht einer klaren Rückmeldung wie „Gericht nicht verfügbar“ statt dem unbrauchbaren Satz „Es ging etwas schief“.

Die Grenze: Ein Restaurantgespräch ist flexibel, ein Softwarevertrag muss präzise und automatisiert prüfbar sein. APIs verarbeiten außerdem parallele Anfragen, Teilfehler und Wiederholungen. Die Metapher erklärt nicht Idempotenz, Autorisierung oder verteilte Zustände vollständig.

1. Entwirf zuerst Ressourcen, fachliche Begriffe und Fehler, danach konkrete URLs.
2. Nutze HTTP-Methoden und Statuscodes entsprechend ihrer Semantik.
3. Definiere IDs, Einheiten, Zeitzonen, Nullwerte und Wertebereiche explizit.
4. Dokumentiere den Vertrag maschinenlesbar und prüfe Requests sowie Responses dagegen.
5. Füge Felder bevorzugt kompatibel hinzu; versioniere nur bei tatsächlich brechenden Änderungen.
6. Trenne Authentifizierung, Autorisierung und fachliche Validierung.
7. Gib Correlation-ID und sichere Fehlerdetails zurück, aber keine internen Geheimnisse.