Seite 10 - REST-API

Code-Generierung aus OpenAPI-Spezifikationen klingt verlockend, produziert in der Praxis aber oft unlesbaren Müll, der sofort manuell gepatcht werden muss. Das zerstört den Hauptvorteil der Generierung. Dieser Artikel zeigt, wie man openapi-generator so konfiguriert, dass der Ausgabecode wartbar ist – und warum Template-Overrides der Schlüssel dazu sind.

Eine REST-API ohne korrekt dokumentierte Sicherheitsanforderungen ist für Konsumenten eine Blackbox. OpenAPI 3.x bietet vier Security-Scheme-Typen, die sich in der Swagger-UI direkt nutzbar machen lassen – wenn man weiß, wie man sie korrekt modelliert, global und endpoint-spezifisch kombiniert und mit Scopes granular steuert.

Wer WebSocket-Endpunkte nur im Browser mit DevTools prüft, verliert Reproduzierbarkeit und Automatisierbarkeit. Mit openssl, curl und websocat lassen sich WebSocket-Verbindungen mit Bash testen, der Handshake manuell nachvollziehen und Verbindungstests direkt in die CI-Pipeline integrieren.

Ein API-Endpoint, der ohne Vorwarnung verschwindet, bricht jede Integration, die ihn nutzt, und beschädigt das Vertrauen externer Entwicklerteams in die gesamte API. Die HTTP-Header Deprecation und Sunset aus RFC 8594 bieten einen standardisierten Weg, eine bevorstehende Abschaltung frühzeitig und maschinenlesbar zu kommunizieren, sodass Clients rechtzeitig reagieren können.

Manuell aus einer OpenAPI-Spec Client-SDKs zu generieren ist fehleranfällig und blockiert Releases. Der openapi-generator in einer CI/CD-Pipeline generiert, validiert und veröffentlicht SDKs automatisch bei jeder Spec-Änderung – mit Spectral-Linting, Breaking-Change-Detection und Contract-Tests als Gates.

Jede Request-Payload, die eine API entgegennimmt, ist aus Sicht von TypeScript zunächst unknown, egal wie vertrauenswürdig der Client erscheint. Dieser Artikel zeigt, wie das Trust-Boundary-Pattern Validierung konsequent an der Systemgrenze verankert, mit Middleware, die vor jedem Handler validiert, typisierten Request-Objekten im restlichen Code und einer strukturierten Fehlerausbreitung, die verhindert, dass ungeprüfte Daten tiefer in die Anwendung vordringen.

Kompression lohnt sich für REST-APIs praktisch immer, weil JSON sich außergewöhnlich gut komprimieren lässt, die eigentliche Frage ist nur, welcher Algorithmus wo zum Einsatz kommt. Gzip ist die sichere, universelle Standardwahl, Brotli erreicht spürbar bessere Kompressionsraten, aber zu einem CPU-Preis, der sich nicht überall auszahlt.

NestJS kombiniert TypeScript-Decorators, Dependency Injection und eine modulare Architektur zu einem Backend-Framework, das Struktur erzwingt statt sie dem Zufall zu ueberlassen. Wer TypeScript mit NestJS lernt, versteht Module, Controller, Provider, DTOs und Guards als zusammenhaengendes System, nicht als lose Sammlung von Funktionen.

Wer jedes Feld einer API Antwort einzeln mit expect prüft, übersieht oft stille Breaking Changes wie neue Pflichtfelder, geänderte Typen oder entfernte Enum Werte. Schema Validierung gegen JSON Schema oder OpenAPI deckt genau diese Fälle automatisch auf, reduziert Testcode erheblich und lässt sich nahtlos in Cypress, Playwright und die CI Pipeline integrieren, damit Frontend und Backend denselben Vertrag verlässlich einhalten.

Arrays als Request- und Response-Datencontainer sind das häufigste Wartungsproblem in Symfony REST APIs: keine Typsicherheit, kein Autocompletion, keine Dokumentation aus dem Code. PHP 8.4 readonly-Properties, der Symfony Serializer und der Symfony Validator machen DTOs zu einem klaren Upgrade – mit weniger Code, mehr Sicherheit und besserer IDE-Unterstützung.