APIs entwerfen

Eine Schnittstelle, englisch API, ist der Vertrag zwischen zwei Teilen eines Systems: zwischen App und Server, zwischen zwei Diensten oder zwischen dem eigenen System und einem Partner. Gute Schnittstellen sind leicht zu verstehen, schwer falsch zu benutzen und halten jahrelang. Schlechte Schnittstellen verursachen Fehler, Rückfragen und teure Umbauten, weil jede Änderung alle Clients betrifft. Deshalb lohnt es sich, beim Entwurf einer API sorgfältig zu sein. Diese Lektion zeigt die gängigen Stile, die wichtigsten Gestaltungsregeln und den Umgang mit Änderungen.

1. Stile im Überblick

Vier Stile begegnen einem in der Praxis immer wieder. Erkunden Sie sie:

Für die meisten Anwendungen ist REST die richtige Grundlage, ergänzt um Webhooks oder Ereignisse für Benachrichtigungen. GraphQL lohnt sich, wenn viele unterschiedliche Clients sehr verschiedene Daten brauchen, etwa eine Web-App, zwei Mobil-Apps und ein Partnerportal. gRPC spielt seine Stärken innerhalb eines Systems aus, wo Geschwindigkeit und strenge Schemata zählen. Ordnen Sie zu:

2. Ressourcen, Methoden, Statuscodes

Eine gute REST-API spricht die Sprache des Fachgebiets. Ressourcen sind Substantive im Plural – Kurse, Buchungen, Mitglieder –, die Methoden beschreiben, was mit ihnen geschieht. GET liest und verändert nichts, POST legt an, PUT oder PATCH ändern, DELETE entfernt. Statuscodes sagen dem Client, wie es ausgegangen ist: 2xx für Erfolg, 4xx für Fehler des Clients, 5xx für Fehler des Servers. Probieren Sie eine kleine Buchungs-API aus:

{ "daten": [ { "id": "k_12", "titel": "Yoga am Morgen" } ], "weiter": "cursor_8f2" }

3. Details, die den Unterschied machen

Einige Entscheidungen wirken klein, prägen aber die Qualität einer API. Paginierung: Listen werden nie vollständig ausgeliefert, sondern seitenweise. Cursor-basierte Paginierung („gib mir die nächsten 20 nach diesem Eintrag“) ist robuster als Seitenzahlen, weil sie auch funktioniert, wenn zwischendurch Einträge hinzukommen. Einheitliche Fehler: Jede Fehlerantwort hat dasselbe Format mit einem maschinenlesbaren Code und einer verständlichen Meldung, etwa nach dem Standard „Problem Details“. Idempotenz: Anlegende Aufrufe akzeptieren einen Idempotenzschlüssel, damit Wiederholungen keine Doppelbuchungen erzeugen. Filter und Felder: Clients können gezielt einschränken, was sie brauchen, statt riesige Antworten zu erhalten.

Auch die Benennung zählt. Felder heißen überall gleich, Zeitangaben folgen einem Standard wie ISO 8601 mit Zeitzone, Geldbeträge werden als ganze Cent mit Währung übertragen, nie als Kommazahl. Solche Konventionen hält man in einem kurzen Styleguide fest, damit alle Endpunkte zueinander passen – auch wenn sie von verschiedenen Personen gebaut werden.

4. Versionierung und Änderungen

Schnittstellen leben lange, und Clients lassen sich nicht immer sofort aktualisieren – Apps auf Telefonen bleiben monatelang auf alten Versionen. Deshalb gilt: Abwärtskompatible Änderungen, etwa neue optionale Felder oder neue Endpunkte, sind jederzeit möglich. Brechende Änderungen, etwa umbenannte oder entfernte Felder, verlangen eine neue Version, zum Beispiel /v2 im Pfad oder über einen Header. Die alte Version wird eine angekündigte Zeit weiter betrieben, markiert und erst dann abgeschaltet, wenn die Nutzung nachweislich gering ist.

5. Schema zuerst

Bewährt hat sich, die Schnittstelle zuerst als Beschreibung festzulegen, bevor Code entsteht – bei REST meist mit OpenAPI. Aus dieser Beschreibung lassen sich Dokumentation, Testdaten, Client-Bibliotheken und automatische Prüfungen erzeugen. Frontend und Backend können parallel arbeiten, weil beide denselben Vertrag kennen. Und in der CI-Pipeline lässt sich automatisch prüfen, ob eine Änderung den Vertrag bricht. Gerade wenn Partner oder mehrere Teams eine API nutzen, spart dieses Vorgehen viele Missverständnisse.

6. Ein Beispiel

Ein Yogastudio will seine Kurse über die eigene App und über ein Partnerportal für Firmenfitness buchbar machen. Der Entwurf sieht eine REST-API mit den Ressourcen Kurse, Termine und Buchungen vor, beschrieben in OpenAPI. Listen sind cursor-basiert paginiert, Buchungen verlangen einen Idempotenzschlüssel, Fehler folgen einem einheitlichen Format mit Codes wie „kurs_voll“ oder „termin_vorbei“. Das Partnerportal erhält einen eigenen API-Schlüssel mit Rate Limit und nur den Rechten, die es braucht. Über Webhooks erfährt es von Stornierungen. Als ein Jahr später Wartelisten hinzukommen, werden sie als neues optionales Feld und neuer Endpunkt ergänzt – kein bestehender Client muss angepasst werden. Genau so sieht eine API aus, die mit dem Geschäft wächst, statt es zu bremsen.

Wer eine Schnittstelle entwirft, sollte sich immer in die Lage der Nutzer versetzen: Ist auf Anhieb klar, wie man einen Kurs bucht? Verrät jede Fehlermeldung, was zu tun ist? Und lässt sich die API ausprobieren, ohne vorher lange Dokumentation zu lesen? Wenn diese Fragen mit Ja beantwortet werden, ist die wichtigste Arbeit getan.

7. Dokumentation und Entwicklererfahrung

Eine API wird nur so gut genutzt, wie sie dokumentiert ist. Gute Dokumentation beginnt mit einem kurzen Einstieg: Wie bekomme ich einen Schlüssel, wie sieht die erste Anfrage aus, was kommt zurück? Danach folgen die einzelnen Endpunkte mit Beispielen für Anfragen und Antworten, alle möglichen Fehlercodes mit Erklärung und Hinweise zu Rate Limits, Paginierung und Versionierung. Aus einer OpenAPI-Beschreibung lassen sich interaktive Seiten erzeugen, auf denen man Aufrufe direkt im Browser ausprobieren kann. Eine Testumgebung mit Beispieldaten erlaubt Partnern, ihre Anbindung zu entwickeln, ohne echte Buchungen auszulösen.

Hilfreich ist auch ein Änderungsprotokoll, das jede neue Version, jedes neue Feld und jede Abkündigung mit Datum festhält. Partner abonnieren es und wissen so rechtzeitig, wann sie handeln müssen. Für interne APIs gilt dasselbe in kleinerem Maßstab: Wenn ein anderes Team eine Schnittstelle nutzt, verdient es dieselbe Sorgfalt wie ein externer Kunde. Viele Unternehmen messen inzwischen, wie lange es dauert, bis ein neuer Entwickler die erste erfolgreiche Anfrage stellt. Je kürzer diese Zeit, desto besser ist die Schnittstelle gestaltet – und desto eher wird sie tatsächlich genutzt.

Schließlich lohnt ein Blick auf die Leistung. Jede Anfrage über das Netzwerk kostet Zeit, deshalb sollte ein typischer Bildschirm einer App nicht zwanzig einzelne Aufrufe brauchen. Sinnvoll zusammengestellte Endpunkte, eingebettete Unterressourcen auf Wunsch oder ein eigener Endpunkt für einen häufigen Anwendungsfall verringern die Zahl der Aufrufe. Antworten, die sich selten ändern, tragen Cache-Header, sodass Browser und CDN sie zwischenspeichern können. Und große Listen werden komprimiert übertragen. So bleibt die API auch auf langsamen Mobilverbindungen angenehm schnell.

Stand: September 2026. Kursmaterial der Klarwerk Akademie. Zahlen zu Latenzen und Kosten sind Größenordnungen zur Orientierung, keine Messwerte.