Seite 8 - REST-API

Validierungsfehler, die als rohe HTML-Seite oder als unstrukturiertes JSON-Array ankommen, kosten Frontend-Teams Zeit. RFC 7807 Problem Details definieren ein maschinenlesbares Format, das Symfony mit wenig Aufwand aus der ConstraintViolationList erzeugt – konsistent, dokumentierbar und ohne Framework-Lock-in.

Ohne durchdachte API-Versionierung wird jeder Breaking Change zum Krisenmeeting mit externen Integratoren. In PHP stehen drei etablierte Ansätze zur Auswahl: Versionsnummer in der URI, ein eigener Versions-Header oder Versionierung über den Accept-Header per Content-Negotiation. Welche API-Versionierung passt, hängt von Kundenstruktur, Release-Rhythmus und der Zahl parallel unterstützter Versionen ab.

Die Wahl der richtigen Dokumentations-UI für eine REST API ist keine Kleinigkeit – sie beeinflusst, wie schnell sich externe Entwickler in die API einarbeiten, ob Consumer-Teams API-Endpunkte direkt ausprobieren können, und wie viel Aufwand die Integration in die CI-Pipeline kostet. Swagger UI, Redoc, Scalar und Stoplight Elements haben unterschiedliche Stärken und Philosophien.

API Reviews ohne systematische Checkliste übersehen konsistent dieselben Kategorien: Security-Aspekte, Fehlerformate, Performance und Testabdeckung werden im Zeitdruck gerne übersprungen. Eine strukturierte Checkliste macht Reviews schneller, vollständiger und wiederholbar – und stellt sicher, dass kein PR mit einer kritischen Lücke gemergt wird.

Viele PHP-APIs nennen sich REST, sind aber in Wahrheit RPC-Aufrufe mit HTTP-Verpackung: ein POST-Endpunkt für jede Aktion, immer Statuscode 200, egal was passiert. Echtes RESTful API Design in PHP verlangt Ressourcen statt Aktionen, korrekt eingesetzte HTTP-Verben, durchdachte Statuscodes und Idempotenz, wo sie erwartet wird, und das lässt sich ohne ein einziges Framework sauber umsetzen.

Verschachtelte Ressourcen wie Bestellpositionen unter einer Bestellung wirken auf den ersten Blick intuitiv, führen aber schnell zu unübersichtlichen URL Strukturen und doppelter Autorisierungslogik, wenn sie unüberlegt eingesetzt werden. Dieser Artikel zeigt, wie man Subresources in API Platform sauber über uriTemplate modelliert und wann eine eigenständige Ressource die bessere Wahl ist.

Viele REST-APIs nutzen HTTP als Transportprotokoll, ohne seine Semantik auszuschöpfen. Ressourcen falsch modelliert, Verben falsch eingesetzt, Idempotenz nicht garantiert und Statuscodes willkürlich gewählt – das sind keine Stilfragen, sondern Designfehler mit direkten Auswirkungen auf Caching, Retry-Logik und Client-Implementierung.

Wer APIs implementiert, bevor das Design steht, blockiert Frontend-Teams und zwingt QA-Ingenieure zu manuellem Nachfassen. API-First kehrt die Reihenfolge um: Die OpenAPI-Spezifikation entsteht zuerst, ermöglicht Mocking für Frontend und Contract-Tests für QA – alle Teams entwickeln parallel, ohne aufeinander zu warten.

Webhooks wurden jahrelang außerhalb der API-Dokumentation beschrieben – in separaten Markdown-Dateien, die niemand aktuell hält. OpenAPI 3.1 bringt das neue webhooks-Objekt, das Webhook-Payload-Schemas, Sicherheitsanforderungen und Retry-Verhalten direkt in der Spezifikation verankert.

Eine OpenAPI-Spezifikation, die nur bei Bedarf manuell im Code-Review überprüft wird, driftet über Zeit fast zwangsläufig in Inkonsistenzen: uneinheitliche Feldbenennung, fehlende Fehler-Response-Definitionen, uneinheitliche Pfad-Strukturen. Spectral, ein dediziertes OpenAPI-Linting-Werkzeug, macht diese Konsistenzregeln maschinell prüfbar und in der CI-Pipeline automatisch durchsetzbar, statt sich auf die Aufmerksamkeit einzelner Reviewer zu verlassen.