GraphQL oder REST: wie man sich für eine neue API entscheidet

Worum es geht

GraphQL (zitierte Einführung) ist eine Abfragesprache samt serverseitiger Laufzeitumgebung, die Abfragen gegen ein selbst definiertes Typsystem ausführt; der Client sendet eine Abfrage, die wie die gewünschten Daten geformt ist, und erhält genau diese Daten in einer einzigen Anfrage, und die API entwickelt sich durch das Hinzufügen von Feldern und das Markieren alter als @deprecated weiter, nicht durch Versionierung. Die GraphQL-über-HTTP-Richtlinie (zitiert) beschreibt die operative Form: ein einziger Endpunkt, typischerweise /graphql; POST für Queries und Mutations, optional GET für Queries; und ein 2xx-Status auch dann, wenn die Antwort Fehler enthält, weil HTTP keinen Statuscode für teilweisen Erfolg kennt. Eine API im REST-Stil legt stattdessen Ressourcen unter URLs offen, verwendet Methoden und Statuscodes für die Semantik und stützt sich für Caching und Fehler auf die HTTP-Maschinerie.

Warum es wichtig ist

Die Wahl ist architektonisch und schwer rückgängig zu machen. Sie verändert, wie Caching funktioniert, wie Fehler gemeldet werden, wie Ratenbegrenzungen berechnet werden und welches Tooling Clients brauchen.

So wird es angewendet

• GraphQL wählen, wenn viele unterschiedliche Clients (Web, Mobile, Partner-Apps) verschiedene Ausschnitte eines vernetzten Datengraphen brauchen, wenn Over-Fetching oder Request-Fan-out ein gemessenes Problem sind, und wenn man die Clients genug unter Kontrolle hat, um eine GraphQL-Client-Bibliothek auszuliefern.
• REST wählen, wenn die API ressourcenorientiert und öffentlich ist, wenn HTTP-Caching nach URL wichtig ist, wenn Integratoren Skripte, Webhooks und Agenten sind, die einfaches HTTP sprechen, oder wenn Betriebs-Tooling um Statuscodes und Pfade herum aufgebaut ist.
• Bei der Wahl von GraphQL die Kontrollen einplanen, die die zitierte GraphQL-Sicherheitsrichtlinie beschreibt: Tiefenbegrenzungen, Begrenzungen von Breite und Aliassen sowie Analyse der Abfragekomplexität mit Budgets pro Client; die Spezifikation selbst definiert das nicht. Resolver-Batching für das N+1-Problem einplanen.
• Bei der Wahl von REST Feldauswahl, Filterung und zusammengesetzte Endpunkte einplanen, damit Clients nicht zu vielen Round-Trips gezwungen sind.
• Beides in Betracht ziehen: REST für die öffentliche Oberfläche und Integrationen, GraphQL als Backend-for-Frontend für die eigenen Benutzeroberflächen.

Stolpersteine

GraphQL einführen, um API-Design zu umgehen; das Schema braucht dieselbe Sorgfalt wie Ressourcen-Design. GraphQL nicht vertrauenswürdigen Aufrufern ohne Kostengrenzen offenlegen. Die verschachtelten Include-Parameter einer REST-API so weit wachsen lassen, bis sie eine unbegrenzte Abfragesprache ohne die Validierung von GraphQL sind. CDN-Caching von GraphQL über POST erwarten; GET-Abfragen lassen sich cachen, stossen aber an URL-Längenbegrenzungen.