Konsistenz in einer REST API ist keine aesthetische Praeferenz. Sie ist Usability fuer jeden, der die API nutzt.
Naming-Konventionen
Ressourcen sind Substantive, keine Verben, im Plural fuer Collections. Bei mehrsilbigen Ressourcen empfiehlt sich Kleinschreibung mit Bindestrich. Hierarchische Ressourcen wie die Bestellungen eines bestimmten Nutzers lassen sich verschachteln, allerdings nicht tiefer als drei Ebenen, sonst wird es unhandlich.
Filtering, Sorting, Searching
Filter werden als Query-Parameter uebergeben, Sortierung ebenso, und fuer komplexere Suchanfragen eignet sich ein dedizierter Such-Endpoint. Was dagegen nicht als Query-Parameter gehoert: Auth-Token, weil er in den Header gehoert, und sensible Daten, weil sie in Server-Logs landen.
Paginierung
Offset-basierte Paginierung ist einfach zu implementieren, hat aber Probleme bei sich aendernden Daten, weil neue Eintraege Seiten verschieben. Cursor-basierte Paginierung ist stabiler bei wachsenden Datensaetzen, dafuer etwas komplexer. Jede Response sollte in jedem Fall Paginierungs-Metadaten liefern.
Was in jede Response gehoert
Bei einem Fehler ein strukturiertes Objekt nach dem Standard der Problem Details RFC 7807, bei Erfolg entweder das Ressourcen-Objekt direkt oder umhuellt mit Metadaten.
Checkliste: Ressourcen als Substantive benannt, konsistentes Naming-Schema dokumentiert, Paginierung fuer alle List-Endpoints, Filtering und Sorting ueber Query-Parameter, Fehler-Responses nach RFC 7807, Guidelines in einem Style Guide dokumentiert.
Ein Beispiel aus der Praxis
Eine API hatte fuer aehnliche Listenendpunkte drei verschiedene Paginierungsmuster im Einsatz, teils mit Seitenzahl, teils mit Cursor, teils ganz ohne Begrenzung. Ein Partnerentwickler, der mehrere Endpunkte gleichzeitig integrierte, verlor dadurch spuerbar Zeit, weil er fuer jeden Endpoint erneut recherchieren musste, wie die Paginierung dort funktionierte. Nach der Vereinheitlichung auf ein einziges Cursor-basiertes Muster fuer alle neuen Endpunkte sank die durchschnittliche Integrationszeit fuer neue Partner deutlich.
API-Ueberpruefung oder Style-Guide-Entwicklung gewuenscht? markom.digital entwickelt API-Style-Guides und prueft bestehende APIs auf Konsistenz.
