Ein Bauplan beschreibt das Haus, bevor ein Stein gelegt wird. Eine API-Beschreibung funktioniert wie so ein Bauplan: Sie legt zuerst fest, was gebaut wird.

„API-Beschreibung“ heißt hier: eine Beschreibung der Schnittstelle, über die Programme Daten austauschen. Der Bauherr schaut auf den Plan und weiß: Hier ist die Tür, dort ein Fenster. Erst danach beginnt das Handwerkerteam. Bei Software verhält es sich genauso. Alle Beteiligten lesen dieselbe Zeichnung und stimmen sie ab, bevor irgendein Code entsteht.

Fachlich ist dieser Plan die OpenAPI-Beschreibung, eine maschinenlesbare Beschreibung in YAML, einem Textformat mit Einrückungen, oder JSON. Statt Räume stehen darin Pfade wie /bestellungen; statt Türen stehen Operationen wie GET oder DELETE. Statt Maße beschreibt ein Schema jeden Wert, etwa dass eine Bestellnummer eine Zeichenkette im Format einer UUID sein muss. Ergänzt werden Sicherheitschemata, die festlegen, wie sich ein Client beim Server ausweisen darf.

Konkret: Der Pfad /bestellungen/42 wird mit DELETE gelöscht, /bestellungen mit GET gelesen, nicht als /deleteUser. Wer Design-first arbeitet, entwirft diese Beschreibung zuerst und lässt Server-Gerüst, Client und Request-Validierung daraus erzeugen. Der Server prüft dann jede eingehende Anfrage gegen das Schema.

„Das Bild hat eine Grenze:“ Ein Bauplan ist nach dem Bau oft eingemottet, eine API-Beschreibung bleibt lebendig. Wird sie nicht gepflegt, lügt sie, und der erzeugte Code folgt der Wahrheit nicht mehr.

Schnittstelle zuerst beschreiben heißt: Der Plan ist der Vertrag, nicht der Zufall. Code, der ihm entspringt, folgt ihm.

📌 Design-first · maschinenlesbar · Vertrag

📚 Webentwicklung von Grund auf · Tag 4 von 30
#api #REST #webdev