REST API Design Best Practices — txt1.ai

Von Marcus Chen, Principal API Architect mit 14 Jahren Erfahrung im Aufbau skalierbarer Systeme in Fintech- und Gesundheitsunternehmen

Vor drei Jahren sah ich, wie ein Startup 2,3 Millionen Dollar an Ingenieurskosten verbrannte, weil ihr API-Design fundamental fehlerhaft war. Sie hatten ein Zahlungssystem mit 47 verschiedenen Endpunkten, inkonsistenten Namenskonventionen und keiner Versionierungsstrategie aufgebaut. Als sie eine neue Funktion für ihren größten Kunden hinzufügen mussten, wirkten sich die Änderungen wie Dominosteine auf ihr gesamtes System aus. Nach sechs Monaten Refactoring hatten sie ihren größten Kunden verloren und 40% ihres Engineering-Teams entlassen.

Diese Katastrophe lehrte mich etwas Entscheidendes: API-Design ist nicht nur damit verbunden, Dinge heute zum Laufen zu bringen. Es geht darum, einen Vertrag zwischen Ihrem System und der Welt aufzubauen, der sich über Jahre hinweg elegant weiterentwickeln kann, Millionen von Anfragen verarbeiten und intuitiv genug bleiben kann, dass Entwickler sie tatsächlich verwenden wollen. Nachdem ich über ein Jahrzehnt damit verbracht habe, APIs zu gestalten, die jährlich Milliarden von Transaktionen verarbeiten, habe ich gelernt, dass der Unterschied zwischen einer guten API und einer großartigen häufig auf eine Handvoll grundlegender Prinzipien zurückzuführen ist, die die meisten Teams übersehen.

Die Grundlage: REST über das Schlagwort hinaus verstehen

Als ich 2010 meine Karriere begann, war REST bereits der dominante Architekturstil für Web-APIs, aber ich habe festgestellt, dass viele Entwickler es wie eine Checkliste behandeln, anstatt als Philosophie. REST steht für Representational State Transfer und basiert auf sechs Kernbeschränkungen, die Roy Fielding in seiner Doktorarbeit umriss. Aber hier ist, was in der Praxis zählt: REST bedeutet, Ihre API-Ressourcen als Nomen zu behandeln, HTTP-Methoden als Verben zu verwenden und die Zustandslosigkeit aufrechtzuerhalten.

Das Prinzip der Zustandslosigkeit allein hat mir unzählige Debugging-Stunden erspart. Jede Anfrage vom Client zum Server muss alle Informationen enthalten, die benötigt werden, um diese Anfrage zu verstehen und zu verarbeiten. Kein Sitzungsstatus auf dem Server. Das bedeutet, dass Ihre API horizontal skalieren kann, ohne komplexes Sitzungsmanagement, und jeder Server in Ihrem Cluster jede Anfrage bearbeiten kann. Als ich die Zahlungs-API für eine Gesundheitsplattform entwarf, die täglich 3,2 Millionen Transaktionen verarbeitet, ermöglichte es uns dieses Prinzip, während Spitzenzeiten von 4 Servern auf 47 zu skalieren, ohne eine einzige Zeile Anwendungscode zu ändern.

Aber REST ist kein Dogma. Ich habe gesehen, wie Teams Wochen damit verbringen, darüber zu streiten, ob etwas "wirklich RESTful" ist, während sie sich auf Konsistenz und Benutzerfreundlichkeit konzentrieren sollten. Das Ziel ist es, eine API zu erstellen, die Entwickler intuitiv verstehen können. Wenn Sie HTTP-Methoden korrekt verwenden, Ressourcen logisch organisieren und die Zustandslosigkeit aufrechterhalten, sind Sie bereits zu 90% am Ziel. Die verbleibenden 10% betreffen die praktischen Muster, die Ihre API zu einem Vergnügen machen, anstatt zu einer Quelle der Frustration.

Ressourcennamen: Die Kunst intuitiver URLs

Ihre URL-Struktur ist das erste, was Entwickler sehen, und sie setzt die Erwartungen für Ihre gesamte API. Ich folge einer einfachen Regel: Verwenden Sie Nomen für Ressourcen, halten Sie diese im Plural und organisieren Sie sie hierarchisch, wenn eine klare Eltern-Kind-Beziehung besteht. Zum Beispiel sagt /api/v1/users/12345/orders/67890 sofort, dass Sie die Bestellung 67890 ansehen, die zu Benutzer 12345 gehört.

"Die beste API ist eine, bei der Entwickler den nächsten Endpunkt vor dem Lesen Ihrer Dokumentation vorhersagen können - dann wissen Sie, dass Sie wahre Konsistenz erreicht haben."

Hier liegen die meisten Teams falsch: Sie mischen Verben in ihre URLs. Ich habe APIs mit Endpunkten wie /api/getUser oder /api/createOrder überprüft. Das ist überflüssig, weil HTTP-Methoden bereits die Verben bereitstellen. GET /api/users/12345 ist klarer und RESTful als GET /api/getUser/12345. Die HTTP-Methode sagt Ihnen, welche Aktion Sie durchführen; die URL sagt Ihnen, auf welche Ressource Sie zugreifen.

Konsistenz ist wichtiger als Perfektion. In einem Projekt hatten wir eine Debatte darüber, ob wir /users oder /accounts für unsere Benutzerressource verwenden sollten. Wir verbrachten drei Stunden in diesem Meeting. Wichtig war nicht, welchen Begriff wir wählten, sondern dass wir einen wählten und ihn im gesamten API einhielten. Wir dokumentierten unsere Entscheidung, fügten sie unserem API-Stil-Guide hinzu und machten weiter. Diese Konsistenz bedeutete, dass Entwickler die Endpunktnamen vorhersagen konnten, ohne ständig die Dokumentation überprüfen zu müssen.

Für verschachtelte Ressourcen begrenze ich die Tiefe auf maximal zwei oder drei Ebenen. Darüber hinaus werden URLs unhandlich und die Beziehungen unklar. Wenn Sie sich dabei ertappen, /api/companies/123/departments/456/teams/789/members/012 zu schreiben, sind Sie zu weit gegangen. Überlegen Sie stattdessen, Teams zu einer obersten Ressource mit Abfrageparametern zu machen: /api/teams/789/members?company=123&department=456. Dies hält URLs handhabbar, während es Ihnen weiterhin ermöglicht, Ressourcen angemessen zu filtern und einzugrenzen.

HTTP-Methoden: Das richtige Werkzeug für die Aufgabe verwenden

HTTP bietet uns einen reichen Wortschatz an Methoden, aber ich sehe, dass Entwickler sie konsequent missbrauchen oder sich auf nur GET und POST beschränken. Das Verständnis der semantischen Bedeutung jeder Methode hat mir geholfen, APIs zu erstellen, die sowohl intuitiv als auch zwischenspeicherbar sind. GET ruft Ressourcen ab und muss idempotent und sicher sein – mehrmaliges Aufrufen erzeugt dasselbe Ergebnis ohne Nebenwirkungen. POST erstellt neue Ressourcen. PUT ersetzt eine gesamte Ressource. PATCH aktualisiert einen Teil einer Ressource. DELETE entfernt eine Ressource.

Die Idempotenz von PUT im Gegensatz zu POST ist entscheidend für die Zuverlässigkeit. Als ich eine Bestandsverwaltungs-API für eine Einzelhandelsgruppe mit 847 Filialen baute, verwendeten wir PUT für Updates speziell wegen seiner Idempotenzgarantie. Wenn ein Netzwerkfehler dazu führte, dass eine Anfrage doppelt gesendet wurde, stellte PUT sicher, dass wir keine doppelten Datensätze erstellen oder dieselbe Aktualisierung mehrmals anwenden würden. Diese einzige Entscheidung verhinderte geschätzte 12.000 Bestandsabweichungen im ersten Betriebsjahr.

PATCH wird untergenutzt, ist aber unglaublich wertvoll. Anstatt von den Clients zu verlangen, die gesamte Ressourcenrepräsentation für geringfügige Updates zu senden, erlaubt PATCH teilweise Updates. Wenn Sie ein Benutzerprofil mit 30 Feldern aktualisieren, warum sollten Sie den Client zwingen, alle 30 zu senden, wenn er nur die E-Mail-Adresse ändern möchte? PATCH /api/users/12345 mit einem Body von {"email": "[email protected]"} ist effizienter und weniger fehleranfällig, als die vollständige Ressource zu verlangen.

DELETE sollte ebenfalls idempotent sein. Das Aufrufen von DELETE auf einer bereits gelöschten Ressource sollte 204 No Content oder 404 Not Found zurückgeben und keinen Fehler. Dies macht die Wiederholungslogik einfacher und zuverlässiger. Ich habe weiche Löschungen implementiert, bei denen DELETE eine Ressource als inaktiv markiert, anstatt sie physisch zu entfernen, was eine Prüfspur bietet und eine Wiederherstellung ermöglicht. Der Schlüssel ist, dass nachfolgende DELETE-Aufrufe an dieselbe Ressource dasselbe Ergebnis liefern – die Ressource ist aus der Sicht des Clients verschwunden.

Statuscodes: HTTPs Sprache fließend sprechen