API-Design-Prinzipien für Webanwendungen

API-Design-Prinzipien: APIs bauen, die Entwickler lieben

Eine gut gestaltete API macht Freude bei der Nutzung. Sie ist vorhersagbar, konsistent und tut, was der Entwickler erwartet. Egal, ob Sie eine REST-API, eine GraphQL-API oder etwas anderes bauen, das Befolgen guter Designprinzipien macht Ihre API leichter zu erlernen, zu nutzen und zu integrieren.

Konsistenz ist der Schlüssel

Das wichtigste Prinzip des API-Designs ist Konsistenz. Verwenden Sie überall die gleichen Namenskonventionen — camelCase oder snake_case, aber nicht beides. Verwenden Sie für jeden Endpunkt das gleiche Fehlerformat. Verwenden Sie überall den gleichen Paginierungsansatz. Ein Entwickler, der einen Teil Ihrer API genutzt hat, sollte erraten können, wie ein anderer Teil funktioniert.

Konsistenz gilt auch für das Verhalten von Endpunkten. Wenn eine POST-Anfrage eine Ressource erstellt, sollten alle POST-Anfragen Ressourcen erstellen. Wenn eine DELETE-Anfrage 204 No Content zurückgibt, sollten alle DELETE-Anfragen 204 zurückgeben. Vorhersagbares Verhalten macht Ihre API intuitiv.

Für den Client entwerfen, nicht für die Datenbank

Es ist verlockend, Ihre API-Endpunkte um Ihre Datenbanktabellen herum zu entwerfen. Aber Ihre API sollte den Bedürfnissen Ihrer Clients dienen, nicht Ihr Datenbankschema widerspiegeln. Denken Sie darüber nach, welche Daten Ihre Clients benötigen und wie sie darauf zugreifen möchten. Wenn eine mobile App das Profil eines Benutzers und seine letzten Bestellungen benötigt, stellen Sie einen Endpunkt bereit, der beide in einer Antwort zurückgibt, selbst wenn sie aus verschiedenen Tabellen stammen.

Dies könnte bedeuten, Endpunkte zu erstellen, die Daten aus mehreren Quellen aggregieren. Das ist in Ordnung — die API sollte die Arbeit des Clients erleichtern, nicht erschweren.

Fehler elegant behandeln

Fehler sind unvermeidlich. Eine gute API macht sie leicht verständlich und handhabbar. Verwenden Sie konsistente Fehlerantworten mit einer klaren Struktur. Fügen Sie einen Fehlercode hinzu, den der Client programmatisch parsen kann, eine für Menschen lesbare Nachricht und Details darüber, was schiefgelaufen ist. Geben Sie bei Validierungsfehlern an, welches Feld ungültig war und warum.

Verwenden Sie HTTP-Statuscodes korrekt. Geben Sie nicht 200 mit einer Fehlermeldung im Body zurück — verwenden Sie 400 für fehlerhafte Anfragen, 401 für Authentifizierungsfehler, 403 für Autorisierungsfehler, 404 für nicht gefunden und 500 für Serverfehler. Der Statuscode sagt dem Client auf einen Blick, was passiert ist.

Versionieren Sie Ihre API

Ihre API wird sich ändern. 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.

Stellen Sie alte Versionen mit klaren Zeitplänen als veraltet dar. Fügen Sie einen Sunset-Header in Antworten von veralteten Versionen ein, um Entwickler zu warnen. Entfernen Sie alte Versionen erst, nachdem der Veralterungszeitraum abgelaufen ist.

Gründlich dokumentieren

Eine gut gestaltete API ist dokumentiert. Die OpenAPI-Spezifikation (früher Swagger) ist der Standard für die Dokumentation von REST-APIs. Sie bietet eine maschinenlesbare Beschreibung Ihrer API, die zur Generierung interaktiver Dokumentation, Client-Bibliotheken und Test-Suiten verwendet werden kann. Gute Dokumentation enthält Beispiele, beschreibt Fehlerantworten und erklärt den geschäftlichen Kontext jedes Endpunkts.