Ich erinnere mich noch an den Tag, an dem ich unserem CEO erklären musste, warum unsere mobile App die Datenpläne der Nutzer wie ein Waldbrand verbrauchte. Es war 2016, und ich war seit drei Jahren als Lead API Architect bei einem Fintech-Startup tätig. Unsere REST API gab bei jeder Abfrage des Kontostands komplette Benutzerobjekte zurück – einschließlich Profilbilder, die in base64 kodiert waren. Wir verloren Kunden wie am Fließband, und ich hatte die API entworfen, die uns das Genick brach.
💡 Wichtige Erkenntnisse
- Prinzip 1: Gestalten Sie Ihre API wie ein Produkt, nicht wie eine Datenbank-Hülle
- Prinzip 2: Nutzen Sie HTTP-Statuscodes richtig (aber überdenken Sie sie nicht zu sehr)
- Prinzip 3: Versionieren Sie Ihre API von Anfang an (und machen Sie es richtig)
- Prinzip 4: Gestalten Sie intuitive Ressourcennamen und URL-Strukturen
Diese schmerzhafte Lektion lehrte mich etwas Entscheidendes: Das Design von REST APIs bezieht sich nicht nur darauf, dass alles funktioniert. Es geht darum, dass es gut funktioniert, in großem Maßstab und unter realen Bedingungen, die in Lehrbüchern nie erwähnt werden. In den letzten zwölf Jahren, in denen ich APIs für Unternehmen von 10-Mitarbeiter-Startups bis zu Fortune 500 Unternehmen entwickelt habe, habe ich die gleichen Fehler zahllige Male wiederholt gesehen – und die meisten davon habe ich selbst gemacht.
Heute werde ich die zehn Prinzipien teilen, die meine Art, APIs zu gestalten, verändert haben. Dies sind keine theoretischen Konzepte aus akademischen Arbeiten. Es sind erprobte Richtlinien, die in Produktionsumgebungen entstanden sind, die Millionen von Anfragen pro Tag bearbeiten. Ob Sie Ihre erste API entwickeln oder Ihre zehnte überarbeiten, diese Prinzipien helfen Ihnen, Schnittstellen zu erstellen, die Entwickler tatsächlich nutzen möchten.
Prinzip 1: Gestalten Sie Ihre API wie ein Produkt, nicht wie eine Datenbank-Hülle
Der größte Fehler, den ich beim Design von REST APIs sehe, ist, die API als dünne Schicht über Datenbanktabellen zu betrachten. Ich habe Hunderte von APIs überprüft, bei denen Endpunkte eins zu eins mit Datenbankschemas übereinstimmen und interne Implementierungsdetails offenbaren, die niemals ans Licht der Öffentlichkeit gelangen sollten. Dieser Ansatz schafft brüchige Schnittstellen, die jedes Mal kaputtgehen, wenn sich Ihr Datenmodell weiterentwickelt.
Als ich in meinem aktuellen Unternehmen als VP of Platform Engineering einstieg, hatte unsere API 47 Endpunkte, die direkt unser PostgreSQL-Schema widerspiegelten. Die Änderung eines einzelnen Spaltennamens erforderte die Koordination von Updates in 23 verschiedenen Client-Anwendungen. Die technische Schulden erstickten unsere Innovationsfähigkeit.
Denken Sie stattdessen an Ihre API als Produkt mit einem eigenen Lebenszyklus, Versionsstrategie und Überlegungen zur Benutzererfahrung. Ihren API-Nutzern ist es egal, wie Ihre Datenbanknormalisierungsstrategie oder Ihre interne Mikroservices-Architektur aussieht. Ihnen geht es darum, spezifische Aufgaben effizient zu erledigen.
Überlegen Sie zum Beispiel, anstatt separate Endpunkte für /users, /user_profiles, /user_preferences und /user_settings anzubieten, was Ihre API-Nutzer tatsächlich benötigen. In den meisten Fällen wünschen sie sich einen kohärenten /users/{id} Endpunkt, der eine durchdacht zusammengesetzte Ressource zurückgibt. Verwenden Sie Abfrageparameter wie ?fields=profile,preferences, um es den Nutzern zu ermöglichen, genau das anzufordern, was sie benötigen.
Ich habe diesen Ansatz bei einem Gesundheits-SaaS-Unternehmen implementiert, bei dem wir unsere API-Oberfläche von 89 Endpunkten auf 34 reduziert haben, während wir tatsächlich die Funktionalität erhöhten. Die Antwortzeiten sanken um 43 %, da wir das geschwätzige Hin und Her eliminierten, das aus der Anforderung mehrerer Anfragen resultierte, um grundlegende Informationen zusammenzustellen. Noch wichtiger war, dass unsere API-Dokumentation verständlich wurde und die Einarbeitungszeit für Entwickler von zwei Wochen auf drei Tage sank.
Der Schlüssel liegt im Verständnis des Domänenmodells Ihrer API, das sich erheblich von Ihrem Persistenzmodell unterscheiden kann. Verbringen Sie Zeit mit Ihren API-Nutzern – ob interne Frontend-Teams oder externe Partner – und verstehen Sie deren Arbeitsabläufe. Gestalten Sie Ressourcen rund um deren mentale Modelle, nicht um Ihre Datenbanktabellen.
Prinzip 2: Nutzen Sie HTTP-Statuscodes richtig (aber überdenken Sie sie nicht zu sehr)
HTTP-Statuscodes sind die erste Kommunikationslinie Ihrer API mit den Clients, und trotzdem sehe ich sie ständig missbraucht oder völlig ignoriert. Ich habe einmal eine API auditiert, die immer 200 OK zurückgab, selbst bei Fehlern, während der tatsächliche Status in einem JSON-Feld verborgen war. Die Entwickler dachten, sie seien hilfsbereit, indem sie "immer erfolgreich" waren, aber sie brachen tatsächlich die Fehlerbehandlung jeder HTTP-Client-Bibliothek.
Sie müssen sich nicht alle 63 HTTP-Statuscodes merken, aber Sie müssen die grundlegenden richtig verwenden. Hier ist meine praktische Übersicht basierend auf zwölf Jahren Produktionserfahrung:
- 200 OK: Erfolgreiches GET, PUT oder PATCH, das Inhalt zurückgibt
- 201 Created: Erfolgreiches POST, das eine Ressource erstellt (Location-Header hinzufügen)
- 204 No Content: Erfolgreiches DELETE oder Update, das nichts zurückgibt
- 400 Bad Request: Client hat ungültige Daten gesendet (spezifische Validierungsfehler angeben)
- 401 Unautorisiert: Client wurde nicht authentifiziert