Eine schlecht designte API zu verbessern ist aufwaendig. Sie gleich richtig zu machen, ist die bessere Investition.
Ein Entwickler, der einen Endpoint verstanden hat, sollte alle anderen vorhersagen koennen. Naming, Ressourcenstruktur, Fehlercodes, Paginierung, das sollte ueberall gleich funktionieren.
Klingt offensichtlich. In der Praxis wachsen APIs aber organisch, ein Endpoint nach dem anderen, gebaut von verschiedenen Personen zu verschiedenen Zeiten, ohne gemeinsame Konvention.
Ressourcen, nicht Aktionen
REST ist ressourcenorientiert: der Pfad benennt das Ding, nicht die Aktion. HTTP-Methoden uebernehmen die Aktion, GET zum Lesen, POST zum Erstellen, PUT oder PATCH zum Aktualisieren, DELETE zum Loeschen. Wer Aktionen braucht, die nicht in dieses Schema passen, kann RPC-artige Endpoints als sparsame Ausnahme definieren.
Status Codes richtig einsetzen
200 fuer erfolgreiche GET-Anfragen, 201 nach erfolgreichem POST, 204 fuer DELETE ohne Response-Body, 400 fuer fehlerhafte Client-Eingaben, 401 fuer fehlende Auth, 403 fuer fehlende Berechtigung, 404 fuer nicht gefundene Ressourcen, 500 fuer Serverfehler. Fehler-Responses sollten dabei maschinenlesbar sein, nicht nur eine Fehlermeldung als String.
Versionierung von Anfang an
API-Versionierung ist Pflicht. Eine Versionsangabe im Pfad ist der pragmatische Weg, Header-basierte Versionierung ist eleganter, aber weniger verbreitet. Wichtig ist vor allem: Breaking Changes gehoeren immer in eine neue Version.
Dokumentation als Teil der Entwicklung
Eine OpenAPI-Spec von Anfang an zu fuehren, statt sie nachtraeglich zu erstellen, sorgt fuer eine immer aktuelle Grundlage fuer Mocking, Client-Generierung und Dokumentation.
Checkliste: Konsistentes Naming, HTTP-Methoden korrekt eingesetzt, Status Codes semantisch korrekt, Fehler-Responses maschinenlesbar, Versionierung implementiert, OpenAPI Spec vorhanden, Paginierung fuer alle List-Endpoints.
Ein Beispiel aus der Praxis
Eine gewachsene API hatte ueber die Jahre fuenf verschiedene Konventionen fuer Fehlermeldungen angesammelt, je nachdem, welches Team welchen Endpoint zuletzt angefasst hatte. Ein neuer Partner-Entwickler brauchte dadurch deutlich laenger als erwartet fuer die Integration, weil er fuer jeden Endpoint einzeln herausfinden musste, wie Fehler dort aussehen. Die Einfuehrung eines einheitlichen Fehlerformats nach RFC 7807 fuer alle neuen und schrittweise auch fuer bestehende Endpoints reduzierte die durchschnittliche Integrationszeit neuer Partner spuerbar.
API-Review oder API-Design von Grund auf? markom.digital entwirft REST APIs, die konsistent und gut dokumentiert sind, und prueft bestehende APIs auf Verbesserungspotenzial.
