GraphQL

Was ist GraphQL?

GraphQL ist eine Abfragesprache für APIs und eine Laufzeitumgebung, die diese Abfragen beantwortet. Ein Server veröffentlicht ein stark typisiertes Schema, und der Client sendet eine Abfrage, die genau die gewünschten Felder nennt. Die Antwort spiegelt die Form der Abfrage. Anders als eine typische REST-API wird ein GraphQL-Dienst meist über eine einzige URL angeboten, oft /graphql. Die Sprache ist in der GraphQL-Spezifikation festgelegt.

So funktioniert GraphQL

Schema und Operationen

Das Schema beschreibt die Typen und Felder, die ein Client abfragen kann. Es gibt drei Operationstypen: Eine query liest Daten, eine mutation verändert Daten und löst Nebeneffekte aus, und eine subscription liefert Echtzeit-Updates. Abfragen können Argumente, Variablen, Aliase und Fragmente nutzen, und die Validierung weist eine Abfrage, die nicht zum Schema passt, ab, bevor sie läuft. Resolver erzeugen dann die Daten für jedes Feld.

Eine Anfrage, eine Antwortform

Eine Abfrage nach Name und E-Mail eines Nutzers liefert nur diese beiden Felder unter dem Schlüssel data auf oberster Ebene. Geht etwas schief, enthält die Antwort einen errors-Schlüssel. Eine Anfrage ist üblicherweise ein HTTP-POST mit JSON-Body, der query, operationName und variables enthält. Ein Server darf auch GET akzeptieren, aber nur für Abfragen, nie für Mutationen. Details finden Sie unter GraphQL über HTTP bereitstellen.

Introspection

Mit Introspection kann ein Client das Schema selbst abfragen, über Felder wie __schema und __type. Sie treibt Dokumentationsbrowser und die Autovervollständigung in Editoren an. Laut GraphQL-Dokumentation brauchen APIs, die nur von den eigenen Apps genutzt werden, sie in Produktion oft nicht, und sie zu deaktivieren ist üblich, weil das die Angriffsfläche verkleinert.

Beispiel

Ein Mobil-Bildschirm braucht einen Produktnamen und die drei neuesten Bewertungen. Mit REST kann das einen Aufruf für das Produkt und einen weiteren für die Bewertungen bedeuten. Mit GraphQL sendet der Client eine Abfrage product(id: "42") { name reviews(first: 3) { text } } und erhält genau das zurück. Der Kompromiss verlagert sich auf den Server, der jedes verschachtelte Feld effizient auflösen muss.

Häufige Fehler und Kompromisse

• Das N+1-Problem. Wer eine Liste auflöst und dann zu jedem Eintrag verwandte Daten holt, löst pro Eintrag einen zusätzlichen Backend-Aufruf aus. Batching, etwa mit DataLoader, bündelt diese Abfragen zu einer einzigen Anfrage.
• Unbegrenzte Abfragen. Weil der Client die Abfrage formt, kann eine tief verschachtelte oder sehr breite den Server stark belasten. Paginieren Sie Listenfelder (API-Paginierung) und nutzen Sie Grenzen für Tiefe, Breite und Komplexität sowie Timeouts.
• Schwächeres HTTP-Caching. REST gibt jeder Ressource eine URL, die HTTP-Caches verstehen. GraphQL hat keine solche eingebaute Identität, deshalb sollte die API eine global eindeutige id anbieten, mit der Clients einen Cache aufbauen. Siehe API-Caching.
• HTTP 200 mit Erfolg gleichsetzen. Eine Antwort mit Daten kann trotzdem errors enthalten, und HTTP kennt keinen Status für Teilerfolg. Prüfen Sie den Body, nicht nur den Statuscode.
• Sicherheit allein dem Schema überlassen. Authentifizierung, Autorisierung und Operationsgrenzen gelten weiterhin. Lesen Sie API-Sicherheit.

GraphQL, Lasttests und API-Monitoring

Jede GraphQL-Operation ist eine HTTP-Anfrage an einen Endpunkt. Ein langsamer Resolver oder ein N+1-Muster zeigt sich daher als Antwortzeit unter Last, nicht als fehlschlagende URL. Nutzen Sie Lasttests mit realistischen Abfragen, denn eine günstige und eine teure Abfrage teilen sich dieselbe URL. Für laufende Prüfungen nennt die FAQ des API-Monitorings, dass GraphQL als POST mit JSON-Body unterstützt wird. Fügen Sie eine Assertion auf den Antwort-Body hinzu, damit ein 200 mit errors die Prüfung trotzdem fehlschlagen lässt, und lesen Sie was API-Monitoring ist. Weiterführend: 10 häufige API-Performance-Probleme und wie Sie sie erkennen und wie API-Monitoring Ihrem Unternehmen hilft.

Häufige Fragen (FAQ)

Ist GraphQL eine Datenbank?

Nein. GraphQL ist eine Abfragesprache und Laufzeitumgebung für APIs. Sie sitzt vor Ihren vorhandenen Datenquellen wie Datenbanken, Diensten und anderen APIs, und die Resolver entscheiden, woher jedes Feld stammt.

Worin unterscheiden sich GraphQL und REST?

REST bietet viele URLs, jede mit einer festen Ressourcenform. GraphQL bietet meist einen Endpunkt, bei dem der Client die Felder wählt. GraphQL verringert Over-Fetching, verlagert aber mehr Arbeit und Cache-Komplexität auf die Serverseite.

Nutzt GraphQL für alles POST?

Abfragen und Mutationen werden normalerweise als POST mit JSON-Body gesendet. Laut Leitfaden zur HTTP-Bereitstellung ist GET nur für Abfragen erlaubt, Mutationen müssen POST nutzen.

Sollte ich Introspection in Produktion deaktivieren?

Für APIs, die nur von den eigenen Anwendungen genutzt werden, ist sie in Produktion in der Regel nicht nötig, und das Deaktivieren ist üblich. Sie ist nur ein Teil eines breiteren Ansatzes mit Authentifizierung, Autorisierung, Tiefenlimits und Kostenanalyse.

Kann ich eine GraphQL-API mit LoadFocus überwachen?

Die Seite zum LoadFocus-API-Monitoring nennt GraphQL als unterstützt, und zwar als POST mit JSON-Body. Fügen Sie eine Body-Assertion hinzu, damit Fehler, die mit Status 200 zurückkommen, erkannt werden.