REST Guidelines: Naming, Filtering, Pagination – mit Beispielen.
REST Guidelines: Naming, Filtering, Pagination – die kleinen Details, die riesig wichtig sind
Konsistenz in einer REST API ist keine Schönheitssache. Es ist Usability.
Naming-Konventionen
Ressourcen sind Substantive, keine Verben. /users statt /getUsers. Plurale für Collections. Lowercase mit Bindestrich für mehrsilbige Ressourcen: /blog-posts statt /blogPosts.
Hierarchische Ressourcen: /users/{id}/orders für die Orders eines Users. Nicht tiefer als 3 Ebenen – das wird sonst unhandlich.
Filtering, Sorting, Searching
Filter als Query-Parameter: /users?status=active&role=admin. Sorting: /users?sort=created_at&order=desc. Suche: /users?q=max oder dedizierter /search-Endpoint für komplexere Abfragen.
Was nicht als Query-Parameter: Auth-Token (gehört in den Header), sensitive Daten (werden in Server-Logs geloggt).
Paginierung
Offset-basiert: ?page=2&per_page=20 – einfach zu implementieren, hat aber Probleme bei sich ändernden Daten (Neue Einträge verschieben Seiten). Cursor-basiert: ?after=cursor_token – stabil bei wachsenden Datasets, etwas komplexer zu implementieren.
Response sollte immer Pagination-Metadaten liefern: total, per_page, current_page (bei offset) oder next_cursor (bei cursor-based).
Was in jede Response gehört
Bei Fehler: {"error": {"code": "...", "message": "...", "details": {...}}} (Problem Details RFC 7807 als Standard). Bei Erfolg: entweder das Ressource-Objekt direkt oder umhüllt mit Metadaten.
Checkliste REST Guidelines
Ressourcen als Substantive (nicht Verben)
Konsistentes Naming-Schema dokumentiert
Paginierung für alle List-Endpoints
Filtering und Sorting über Query-Parameter
Fehler-Responses nach RFC 7807
Guidelines in einem API Style Guide dokumentiert
API-Überprüfung oder Style-Guide-Entwicklung?
markom.digital entwickelt API-Style-Guides und prüft bestehende APIs auf Konsistenz.
