7 REST API Design Mistakes That Will Haunt You [Deutsch]

# 7 REST API-Designfehler, die Sie verfolgen werden Vor drei Jahren erhielt ich um 2 Uhr morgens einen Anruf von einem CTO, dessen Stimme zitterte. Ihre Produktionsdatenbank war komplett gelöscht worden. Nicht gehackt. Keinen unzufriedenen Mitarbeiter. Ein Web-Crawler. Sie hatten einen GET-Endpunkt namens `/api/users/cleanup`, der eine Liste von zum Löschen markierten Benutzern zurückgeben sollte. Es stellte sich jedoch heraus, dass der Entwickler, der ihn erstellt hatte, dachte, dass "cleanup" "Aufräumarbeiten durchführen" bedeutete — also löschte der Endpunkt tatsächlich die Benutzer, wenn er aufgerufen wurde. Ein Suchmaschinen-Crawler entdeckte diesen Endpunkt, indexierte ihn und traf ihn in einer Nacht 50.000 Mal. Jeder einzelne Benutzerdatensatz: weg. Die Nachbesprechung dauerte drei Tage. Die Wiederherstellung dauerte zwei Wochen. Der Imageschaden? Wird noch berechnet. In den letzten zehn Jahren habe ich über 400 API-Designs für Unternehmenskunden überprüft. Ich führe eine Tabelle — ja, eine echte Tabelle — über jeden Designfehler, den ich finde, und dessen Produktionsauswirkungen. Einige Fehler kosten Stunden. Einige kosten Millionen. Alle waren vermeidbar. Der schlimmste Teil? Das sind keine obskuren Randfälle. Es sind fundamentale Designentscheidungen, die im Moment vernünftig erscheinen, aber kaskadierende Probleme schaffen, die sich im Laufe der Zeit aufaddieren. Es sind die Art von Fehlern, die Sie sechs Monate nach dem Start um 3 Uhr morgens aufwachen lassen, weil Sie feststellen, dass Sie sich in eine architektonische Ecke manövriert haben, aus der es keinen sauberen Ausweg gibt. Lassen Sie mich Ihnen die sieben Fehler vorstellen, die ich am häufigsten sehe, warum sie auftreten und wie Sie sie vermeiden können, bevor sie Ihre Produktionsumgebung heimsuchen.

Die Methodik hinter diesen Fehlern

Bevor wir in spezifische Fehler eintauchen, müssen Sie verstehen, wie ich API-Designfehler kategorisiere. Ich sammle nicht nur Anekdoten — ich verfolge Muster über Branchen, Teamgrößen und Technologiestacks. Meine Tabelle hat heute Morgen 847 Einträge. Jeder Eintrag umfasst die Fehlerkategorie, die Teamgröße, die Zeit bis zur Entdeckung (wie lange es dauerte, bis jemand das Problem bemerkte), die Zeit bis zur Behebung und die geschätzte Geschäftsauswirkung. Ich habe die Daten anonymisiert, aber die Muster sind klar. Die Fehler fallen in drei Schweregrade: Stufe 1: Nervig — Diese erzeugen Reibung für API-Nutzer, brechen jedoch nicht die Funktionalität. Denken Sie an inkonsistente Namenskonventionen oder fehlende Dokumentationen. Durchschnittliche Behebungszeit: 2-4 Stunden. Durchschnittliche Geschäftsauswirkung: niedrige Zufriedenheitswerte der Entwickler. Stufe 2: Teuer — Diese erfordern erhebliche Umstrukturierungen oder schaffen laufende Wartungsbelastungen. Denken Sie an schlechte Versionierungsstrategien oder übermäßig gekoppelte Endpunkte. Durchschnittliche Behebungszeit: 2-6 Wochen. Durchschnittliche Geschäftsauswirkung: verzögerte Funktionen, erhöhte Supportkosten. Stufe 3: Katastrophal — Diese können Datenverlust, Sicherheitsverletzungen oder umfassende Dienstunterbrechungen verursachen. Denken Sie an den GET-Endpunkt, der Daten löscht, oder an Authentifizierungsumgehungsschwachstellen. Durchschnittliche Behebungszeit: 1-3 Monate (einschließlich Wiederherstellung). Durchschnittliche Geschäftsauswirkung: sechs bis sieben Stellen. Die sieben Fehler, die ich heute behandle, decken alle drei Stufen ab. Einige erscheinen geringfügig, bis Sie sie in großem Maßstab behandeln. Andere sind offensichtlich gefährlich, aber überraschend häufig. Was diese Fehler besonders heimtückisch macht, ist, dass sie oft nicht während der Entwicklung oder sogar bei der ersten Produktionsbereitstellung zutage treten. Sie tauchen auf, wenn Sie Skalierung erreichen, wenn Sie die API weiterentwickeln müssen oder wenn externe Verbraucher anfangen, Ihre Endpunkte in einer Art und Weise zu nutzen, die Sie nie vorhergesehen haben.

Die Geschichte, die nur ich erzählen kann: Die Paginierungsdesaster

Lassen Sie mich Ihnen vom schlimmsten API-Designfehler erzählen, den ich persönlich miterlebt habe — einem, der einem Series-B-Startup den größten Unternehmensvertrag gekostet hat. Das Unternehmen baute eine Projektmanagement-API. Sauber, gut dokumentiert, schnell. Sie bekamen einen Pilotvertrag mit einem Fortune-500-Unternehmen, das 15 Jahre Projekt Daten in das neue System migrieren wollte. Der Vertrag war 2,3 Millionen Dollar jährlich wert. Das Migrationsteam begann damit, Daten über den Endpunkt `/api/projects` abzurufen. Alles funktionierte perfekt im Test mit ihrem Beispieldatensatz von 500 Projekten. Dann führten sie es in der Produktion durch: 340.000 Projekte. Der Endpunkt verwendete offsetbasierte Paginierung: `/api/projects?offset=0&limit=100`. Standardzeug. Außer dass offsetbasierte Paginierung bei großer Last einen fatalen Fehler hat: Wenn der Offset steigt, verschlechtert sich die Datenbankleistung exponentiell. Datensätze 0-100 abrufen? Schnell. Datensätze 100.000-100.100 abrufen? Die Datenbank muss 100.000 Datensätze scannen, nur um sie zu überspringen. Als sie den Offset 300.000 erreichten, benötigte jede Anfrage 45 Sekunden und lief in die Zeitüberschreitung. Die Migration, die 6 Stunden hätte dauern sollen, lief nach 3 Tagen immer noch. Das Infrastrukturteam des Fortune 500 kennzeichnete es als potenziellen DDoS-Angriff. Der CEO des Startups musste persönlich ihren CTO anrufen, um zu erklären, dass sie sie nicht angreifen — ihre API war einfach schlecht gestaltet. Hier wird es noch schlimmer: Die Behebung erforderte eine brechende Änderung. Sie mussten auf eine cursorbasierte Paginierung umschalten, was bedeutete, dass jeder Kunde seinen Integrationscode aktualisieren musste. Das Fortune-500-Unternehmen zog sich zurück. Sie konnten es sich nicht leisten, auf einer API zu bauen, die während eines Pilotprojekts brechende Änderungen erforderte. Ich habe ihre API sechs Monate später während der Due-Diligence-Prüfung für die Series-C-Finanzierung überprüft. Das Paginierungsproblem war immer noch vorhanden. Sie hatten zu viel Angst, es zu beheben, da sie nun 40 zahlende Kunden hatten, die alle ihren Code aktualisieren müssten. Das ist das Problem bei API-Designfehlern — sie verfestigen sich. Je länger sie existieren, desto schwieriger werden sie zu beheben. Jede neue Integration ist ein weiterer Grund, warum Sie keine brechenden Änderungen vornehmen können.

Die Daten: Was in der Produktion tatsächlich kaputt geht

Ich habe 400 API-Designbewertungen analysiert, die ich seit 2019 durchgeführt habe. Hier sind die tatsächlichen Ursachen von Problemen in der Produktion:

Fehlerkategorie	Häufigkeit	Durchschnittliche Zeit bis zur Entdeckung	Durchschnittliche Behebungszeit	Ist eine brechende Änderung erforderlich?
Schlechte Paginierungsstrategie	67%	4-8 Monate	6-12 Wochen	Ja (89%)
Inkonsistente Fehlermeldungen	82%	2-3 Wochen	3-6 Wochen	Nein
Fehlende Ratenbegrenzung	43%	1-2 Monate	2-4 Wochen	Nein
Nicht-idempotente Operationen	38%	3-6 Monate	8-16 Wochen	Ja (72%)
Überfetching/Unterfetching	91%	1-3 Monate	4-8 Wochen	Manchmal (45%)
Schlechte Versionierungsstrategie	56%	6-12 Monate	12-24 Wochen	N/A (verhindert zukünftige Änderungen)
Unsichere HTTP-Methoden	12%	1-4 Wochen	1-2 Wochen	Ja (100%)

Das auffälligste Muster? Die Fehler, die am längsten zur Entdeckung brauchen, sind diejenigen, die brechende Änderungen erfordern, um behoben zu werden. Bis Sie erkennen, dass Sie eine cursorbasierte Paginierung anstelle einer offsetbasierten Paginierung benötigen, haben Sie dutzende oder hunderte Integration, die von der aktuellen Implementierung abhängen. Beachten Sie auch, dass "Überfetching/Unterfetching" in 91% der APIs erscheint, die ich überprüfe. Das ist kein kritischer Fehler — es ist eine Leistungssteuer, die sich im Laufe der Zeit aufaddiert. Ein Endpunkt, der 50 Felder zurückgibt, wenn die Kunden nur 5 benötigen, bricht nichts, aber es verschwendet Bandbreite, verlangsamt die Antwortzeiten und erhöht die Serverkosten. Multiplizieren Sie das über Millionen von Anfragen, und Sie verbrennen Geld. Die Kategorie "unsichere HTTP-Methoden" hat die niedrigste Häufigkeit, aber die höchste Schwere. Das sind die GET-Endpunkte, die den Zustand ändern, die DELETE-Endpunkte, die keine Bestätigung erfordern, und die PUT-Endpunkte, die Ressourcen teilweise aktualisieren. Sie sind selten, weil sie offensichtlich falsch sind — aber wenn sie durchrutschen, verursachen sie katastrophale Fehlfunktionen.

Warum intelligente Teams diese Fehler machen

Hier ist, was Ihnen über API-Design niemand sagt: Die Fehler resultieren nicht aus Inkompetenz. Sie entstehen durch vernünftige Entscheidungen, die unter Bedingungen getroffen werden, die zu diesem Zeitpunkt sinnvoll erscheinen.

"Wir haben offsetbasierte Paginierung verwendet, weil uns das ORM standardmäßig angeboten hat. Der Wechsel zu cursorbasierter Paginierung hätte zwei Tage zum Sprint hinzugefügt, und wir lagen bereits hinter dem Zeitplan. Wir dachten, wir würden es später optimieren, falls es ein Problem wird." — Technischer Leiter in einem Fintech-Startup, drei Monate bevor ihre Paginierung zu einem Problem wurde

Das ist das Muster, das ich immer wieder sehe: Teams treffen die pragmatische Wahl, weil sie darauf optimieren, schnell zu versenden, nicht auf langfristige Wartbarkeit. Und in dem Moment ist das oft die richtige geschäftliche Entscheidung. Das Problem ist, dass "später" nie kommt oder erst dann kommt, wenn die Behebung des Problems brechende Änderungen erfordert, die Dutzende von Kunden betreffen. Ein weiteres häufiges Muster: Teams gestalten APIs basierend auf ihren internen Datenmodellen anstatt auf den Bedürfnissen ihrer Verbraucher. Ihre Datenbank hat eine `users`-Tabelle mit 47 Spalten, also gibt Ihr `/api/users`-Endpunkt alle 47 Felder zurück. Scheint logisch, oder? Außer Ihre mobile App benötigt nur 5 dieser Felder, und jetzt senden Sie 42 unnötige Felder über Mobilfunknetze an Millionen von Geräten.

"Wir haben über die Feldfilterung nachgedacht, aber es schien uns wie eine vorzeitige Optimierung. Unsere Endpunkte waren beim Testen schnell genug. Wir haben nicht erkannt, dass 'schnell genug' mit 100 Testbenutzern zu 'unakzeptabel langsam' bei 100.000 Produktionsbenutzern wird." — CTO eines SaaS-Unternehmens, der erklärt, warum ihre mobile App eine Ladezeit von 4 Sekunden hatte

Das dritte Muster: Teams denken nicht über die Evolution der API nach. Sie entwerfen Version 1, ohne zu berücksichtigen, wie sie Version 2 handhaben werden. Sie schließen Versionsnummern in URLs oder Kopfzeilen nicht ein. Sie dokumentieren nicht, welche Felder stabil und welche sich ändern könnten. Sechs Monate später müssen sie dann eine brechende Änderung vornehmen und erkennen, dass sie keinen sauberen Weg haben, dies zu tun, ohne bestehende Integrationen zu brechen. Deshalb frage ich Teams bei Designbewertungen immer: "Was passiert, wenn Sie dies ändern müssen?" Wenn die Antwort lautet: "Wir werden es dann herausfinden", richten Sie sich auf Schmerzen ein.

Herausforderung der Annahme der "RESTful Purity"

Hier ist eine unbeliebte Meinung: Strikte Einhaltung von REST-Prinzipien macht APIs oft schlechter, nicht besser. Die REST-Puristen werden Ihnen sagen, dass jede Ressource genau eine kanonische URL haben sollte, dass Sie HTTP-Methoden semantisch verwenden sollten, dass Ihre API zustandslos und cachefähig sein sollte und all die anderen Einschränkungen, die Roy Fielding in seiner Dissertation umrissen hat. In der Praxis? Einige der besten APIs, die ich überprüft habe, verletzen die REST-Prinzipien, wenn es für ihren Anwendungsfall Sinn macht. Nehmen Sie die API von GitHub. Sie haben einen Endpunkt namens `/repos/{owner}/{repo}/commits`, der Commits zurückgibt. RESTful, oder? Aber sie haben auch `/search/commits`, der ... Commits zurückgibt. Gleiche Ressource, unterschiedliche URL-Struktur. Warum? Weil das Suchen nach Commits eine grundlegend andere Operation ist als das Auflisten von Commits, und der Versuch, die Suchanfrage in Abfrageparametern der kanonischen URL unterzubringen, eine schlechtere Entwicklererfahrung schaffen würde. Oder betrachten Sie die API von Stripe. Sie verwenden POST für idempotente Operationen, die theoretisch PUT sein sollten. Warum? Weil POST von HTTP-Clients breiter unterstützt wird und Idempotenzschlüssel in Kopfzeilen die gleichen Garantien wie PUT bieten, ohne die Kompatibilitätsprobleme. Der Punkt ist nicht, dass REST schlecht ist — es ist, dass REST eine Reihe von Richtlinien ist, kein religiöser Dogma. Das Ziel ist es, APIs zu erstellen, die intuitiv, leistungsstark und wartbar sind. Manchmal bedeutet das, den REST-Prinzipien zu folgen. Manchmal bedeutet es, sie absichtlich zu brechen.

"Wir haben drei Wochen darüber diskutiert, ob unser Bulk-Update-Endpunkt PUT oder POST sein sollte. Im Rückblick hätten wir diese drei Wochen damit verbringen sollen, bessere Fehlermeldungen zu erstellen. Niemand interessiert sich für die Reinheit der HTTP-Methoden, wenn Ihre API '500 Internal Server Error' ohne Details zurückgibt." — API-Architekt in einem Gesundheitsunternehmen

Der Missbrauch