Bewährte Methoden für das Design von REST-APIs

REST-APIs entwerfen, die Menschen gerne nutzen werden

Eine gut gestaltete API macht Freude bei der Arbeit. Sie ist vorhersagbar, konsistent und tut, was Sie erwarten. REST (Representational State Transfer) ist der häufigste Architekturstil für das Design von APIs, und das Befolgen seiner Konventionen macht Ihre API einfacher zu erlernen, zu verwenden und zu warten.

Denken Sie in Ressourcen, nicht in Aktionen

Die Kernidee von REST ist, dass Sie Ihre API um Ressourcen herum modellieren – die Dinge, die Ihr System verwaltet, wie Benutzer, Bestellungen, Produkte oder Artikel. Jede Ressource hat eine URL, die sie identifiziert. Sie verwenden HTTP-Methoden, um anzugeben, was Sie tun möchten: GET zum Abrufen, POST zum Erstellen, PUT zum Ersetzen, PATCH zum Aktualisieren und DELETE zum Entfernen.

URLs sollten Substantive sein, keine Verben. Verwenden Sie /users anstelle von /getUsers und /orders anstelle von /createOrder. Ressourcen können verschachtelt werden, um Beziehungen darzustellen: /users/123/orders repräsentiert die Bestellungen, die zu Benutzer 123 gehören. Das macht Ihre API intuitiv – Entwickler können die URLs erraten, ohne die Dokumentation zu lesen.

Verwenden Sie HTTP-Statuscodes richtig

HTTP-Statuscodes sind Ihre Möglichkeit, dem Client mitzuteilen, was passiert ist. 200 bedeutet, dass alles funktioniert hat. 201 bedeutet, dass eine Ressource erstellt wurde (und Sie sollten einen Location-Header einfügen, der darauf verweist). 204 bedeutet, dass die Anfrage erfolgreich war, aber kein Inhalt zurückgegeben wird. 400 bedeutet, dass der Client etwas Ungültiges gesendet hat. 401 bedeutet, dass er sich authentifizieren muss. 403 bedeutet, dass er nicht berechtigt ist. 404 bedeutet, dass die Ressource nicht gefunden wurde. 429 bedeutet, dass er ratenbegrenzt wurde. Und 500 bedeutet, dass auf dem Server etwas schief gelaufen ist.

Die konsequente Verwendung der richtigen Statuscodes macht Ihre API viel einfacher zu debuggen. Clients können Fehler programmatisch behandeln, anstatt Fehlermeldungen zu parsen. Tools wie HTTP-Clients und API-Bibliotheken können besseres Feedback geben, wenn sie die Statuscodes verstehen.

Versionieren Sie Ihre API von Anfang an

Selbst wenn Sie denken, dass Ihre API perfekt ist, werden Sie sie irgendwann ändern müssen. Versionierung ermöglicht es Ihnen, Änderungen vorzunehmen, ohne bestehende Clients zu beeinträchtigen. Der einfachste Ansatz ist, die Version in die URL aufzunehmen: /api/v1/users, /api/v2/users. Wenn Sie eine bahnbrechende Änderung vornehmen müssen, erstellen Sie eine neue Version und geben Sie den Clients Zeit zur Migration.

Sobald eine Version veraltet ist, fügen Sie einen Sunset-Header in die Antworten ein, um Clients zu warnen, dass die alte Version irgendwann entfernt wird. Dies gibt ihnen Zeit, um zu aktualisieren.

Behandeln Sie Paginierung, Filterung und Sortierung

Wenn eine API eine Liste von Ressourcen zurückgibt, sollte sie Paginierung unterstützen, damit Clients Daten in überschaubaren Blöcken anfordern können. Cursor-basierte Paginierung ist für große Datensätze leistungsfähiger als seitenbasierte. Erlauben Sie Clients, Ergebnisse nach allgemeinen Feldern zu filtern, und lassen Sie sie die Sortierreihenfolge festlegen. Fügen Sie Metadaten in die Antwort ein, damit Clients wissen, wie sie die nächste Seite erhalten.

Geben Sie konsistente Fehlerantworten zurück

Wenn etwas schief geht, sollte Ihre API eine konsistente Fehlerstruktur zurückgeben, die Clients parsen können. Fügen Sie einen Fehlercode, eine für Menschen lesbare Nachricht und Details darüber, was schief gelaufen ist, hinzu. Geben Sie bei Validierungsfehlern an, welches Feld ungültig war und warum. Es gibt ein Standardformat namens RFC 7807 (Problem Details for HTTP APIs), dem viele APIs folgen.

Sichern Sie Ihre API

Verwenden Sie Bearer-Tokens (wie JWT) im Authorization-Header zur Authentifizierung. Verwenden Sie API-Schlüssel für die Server-zu-Server-Kommunikation. Implementieren Sie OAuth 2.0 für delegierten Zugriff. Begrenzen Sie die Anfragen pro Client immer, um Missbrauch zu verhindern. Und protokollieren Sie jede Anfrage für Überwachung und Debugging.

Dokumentieren und testen

Eine gute API ist dokumentiert. Die OpenAPI-Spezifikation (früher Swagger) ist der Standard, um REST-APIs zu beschreiben. Tools können aus Ihrer OpenAPI-Spezifikation interaktive Dokumentation, Client-Bibliotheken und Testsuiten generieren. Vertragstests stellen sicher, dass sich Ihre API wie dokumentiert verhält, und Mock-Server ermöglichen es Clients, gegen Ihre API zu entwickeln, bevor sie fertig ist.