API-Design: Versionierung, Pfade, Idempotency-Key
Für HTTP-Schnittstellen haben sich Konventionen herausgebildet, die nicht genormt sind. Die Seite zeigt gängige Arten der Versionierung, REST-Pfade für Sammlung und Element, Query-Parameter für Filter, Sortierung und Feldauswahl und einen Ablauf mit Idempotency-Key gegen doppelte Buchungen. Die Namen der Parameter sind erfunden und dienen nur als Muster.
4 Varianten auf einer Seite, jede mit eigenem Kopier- oder Download-Knopf. Darunter: 1× Fiktiv.
Gängige Arten der API-Versionierung
Im Pfad: /v2/kunden Im Header: X-API-Version: 2 Im Medientyp: Accept: application/vnd.example.v2+json …
Vier Verfahren mit Vor- und Nachteilen; keine ist genormt.
REST-Pfadkonventionen
GET /kunden POST /kunden GET /kunden/{id} …Sammlung und Element, Unterressource.
Query-Parameter für Filter, Sortierung, FelderFiktiv
GET /kunden?ort=Berlin&sortierung=-erstellt&felder=id,name&seite=2&pro_seite=25
Minus vor dem Feld = absteigend; Namen erfunden.
Ablauf mit Idempotency-Key
POST /zahlungen Idempotency-Key: 5a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d -> 201 Created (erste Anfrage) …
Schützt vor Doppelbuchung bei Wiederholungen.