Seite 5 - REST-API

Schlechte API-Dokumentation kostet Frontend-Teams Stunden für Rückfragen, die sich nie hätten stellen müssen. Konsistente Response-Struktur, maschinenlesbare Fehlerformate und vollständige Typisierung machen aus einer API-Spezifikation ein Werkzeug, das Frontend-Entwickler vom ersten Tag an produktiv einsetzt.

JWT oder Sessions für Symfony REST-APIs? Die Antwort hängt von Skalierungsanforderungen, Revokationsbedarf, Client-Typ und Sicherheitsmodell ab. Wer den Unterschied zwischen stateless und stateful Authentifizierung versteht, trifft die richtige Entscheidung für seinen konkreten Anwendungsfall.

API Platform generiert OpenAPI-Dokumentation aus PHP-Klassen – das spart Stunden manueller Arbeit. Aber Schema-Namen mit internen Zählern, fehlende Beispiele, rudimentäre Security-Definitionen und nicht dokumentierte Fehlerfälle zeigen, wo das Automatismus-Versprechen seine Grenzen hat. Dieser Artikel zeigt konkret, was gut funktioniert – und was überschrieben werden muss.

Eine REST-API, die bei jedem Request dieselben Daten aus der Datenbank lädt und vollständig zurücksendet, verschwendet Bandbreite und Serverressourcen. ETag, Last-Modified und Cache-Control sind die HTTP-Standard-Werkzeuge, die genau das verhindern – mit 304 Not Modified für unveränderte Ressourcen und Proxy-Caching für öffentliche Daten.

Eine REST-API, die niemals Breaking Changes durchführt, ist eine API, die niemals wirklich weiterentwickelt wird. Wer Deprecations, Sunset-Dates und Migrationspfade von Anfang an einplant, kann APIs gezielt weiterentwickeln, ohne Integratoren zu verlieren oder ohne Vorwarnung zu brechen.

Eine OpenAPI-Spezifikation, die nur für die Dokumentation existiert, bringt wenig. Wer sie als bindenden Vertrag zwischen Frontend, Backend und externen Konsumenten behandelt – und sie mit Contract-Tests, RFC-7807-Fehlerformaten, Security-Schemas und automatisiertem Tooling absichert – macht aus einer YAML-Datei ein produktives Qualitätswerkzeug.

Eine öffentliche API ohne Rate Limiting ist eine offene Einladung für Abuse. Token-Bucket- und Sliding-Window-Algorithmen begrenzen die Anfragelast pro Client, API-Keys ermöglichen differenzierte Limits und Abuse-Prevention-Patterns erkennen und blockieren missbräuchliches Verhalten – bevor es die Infrastruktur trifft.

Schlechte API-Fehlerantworten kosten Entwicklungszeit – auf beiden Seiten. Wenn Consumers nur {"error": "Something went wrong"} bekommen, können sie weder programmatisch reagieren noch gezielt debuggen. RFC 9457 Problem Details for HTTP APIs, maschinenlesbare Error Codes, strukturierte Feldfehler und Correlation IDs machen Fehlerfälle zu einem First-Class-Feature der API – nicht zu einem Afterthought.

Alternative Formate und Massenoperationen stellen REST-APIs vor echte Designprobleme: Wann Content-Negotiation, wann eigene Endpunkte? Wie werden tausende Datensätze performant gestreamt? Wie kommuniziert eine Bulk-Operation partielle Fehler klar genug, damit Clients sinnvoll reagieren können?

Ein Backoffice-API und eine Public API teilen HTTP als Transport – aber ihre Anforderungen an Stabilität, Abwärtskompatibilität, Sicherheit und Fehlermodelle unterscheiden sich so fundamental, dass ein einheitliches Design zwangsläufig eines von beidem schlechter macht.