Abfragesprache für Schnittstellen

Was ist GraphQL?

Graph Query Language

GraphQL ist eine Abfragesprache für Programmierschnittstellen, bei der ein typisiertes Schema festlegt, welche Daten es gibt, und der aufrufende Client in seiner Anfrage genau die Felder benennt, die er braucht.

Wenn eine App für einen einzigen Bildschirm fünf Schnittstellen abklappert und dabei ein Vielfaches der benötigten Daten lädt, kommt GraphQL im Team auf den Tisch.

KI-generiertDieses Bild wurde mit KI erzeugt · Yves Hoppe / KI / cmt

Entstanden bei: Facebook, öffentlich seit 2015
Heute bei: GraphQL Foundation
Aufbau: Ein Endpunkt, ein typisiertes Schema
Bekanntes Problem: N+1-Abfragen in den Resolvern

Schema, Query, Mutation, Resolver

Am Anfang steht das Schema. Es beschreibt Typen und Felder, etwa einen Typ Benutzer mit den Feldern name und projekte, und ist gleichzeitig Dokumentation und Vertrag. Werkzeuge lesen es aus und bieten Autovervollständigung im Editor an, ohne dass jemand eine Extra-Doku pflegt.

Lesende Anfragen heißen Query, schreibende heißen Mutation, und für laufende Aktualisierungen über eine offene Verbindung gibt es die Subscription. Query und Mutation gehen an denselben Endpunkt, meist per POST. Die Antwort hat exakt die Form der Anfrage: Fragst du den Namen und die Titel der Projekte ab, bekommst du genau diese beiden Felder zurück, verschachtelt, wie du sie notiert hast.

Hinter jedem Feld steht auf dem Server ein Resolver, also eine kleine Funktion, die den Wert beschafft. Woher er ihn hat, ist GraphQL egal: aus einer Datenbank, aus einem anderen Dienst, aus dem Cache. Genau deshalb lässt sich GraphQL auch als Fassade vor bestehende Systeme legen.

Warum Teams das einführen

Der übliche Auslöser ist eine App, die für einen einzigen Bildschirm drei Endpunkte nacheinander aufrufen muss und dabei jedes Mal Felder mitbekommt, die niemand anzeigt. Mit GraphQL wird daraus eine Anfrage, die genau die Felder dieses Bildschirms enthält.

Der zweite Grund ist die Entkopplung. Wenn das Frontend ein neues Feld braucht, wird es dem Schema hinzugefügt, alte Abfragen bleiben gültig. Versionierte Pfade wie /v2/ entfallen meist, stattdessen markierst du alte Felder als deprecated und siehst in der Auswertung, wer sie noch abruft.

Was dabei schiefgeht

Das bekannteste Problem heißt N plus 1: Ein Resolver für eine Liste fragt für jeden Eintrag einzeln die Datenbank ab, aus einer Abfrage werden hunderte. Die Standardantwort ist ein Batching-Layer nach dem Muster von DataLoader, der die Einzelabrufe innerhalb eines Durchlaufs sammelt und gebündelt ausführt.

Das zweite ist die Angriffsfläche. Weil Clients Abfragen frei zusammenbauen, kann eine tief verschachtelte Anfrage einen Server über Gebühr beschäftigen. Üblich sind deshalb eine Begrenzung der Verschachtelungstiefe, Kostenbudgets pro Abfrage und im Produktivbetrieb oft nur vorab registrierte Abfragen.

Und schließlich das Caching: REST profitiert davon, dass sich Antworten auf GET über die URL zwischenspeichern lassen. Bei GraphQL läuft alles über einen Endpunkt, das HTTP-Caching greift kaum, dafür halten die Client-Bibliotheken die Daten normalisiert im Speicher.

KI-generiertDieses Bild wurde mit KI erzeugt · Yves Hoppe / KI / cmt

Nicht verwechseln

GraphQL und was oft damit gleichgesetzt wird

GraphQL gegen REST

REST verteilt Daten auf mehrere Ressourcen-URLs, deren Antwortform der Server festlegt. Bei GraphQL gibt es einen Endpunkt und der Client bestimmt den Ausschnitt. Dafür verlierst du das einfache HTTP-Caching und die Statuscodes als Fehlersprache, GraphQL antwortet meist mit 200 und einem errors-Feld.

GraphQL gegen gRPC

gRPC ist ebenfalls typisiert, richtet sich aber an die Kommunikation zwischen Diensten und ruft Prozeduren auf, statt Datengraphen abzufragen. GraphQL sitzt typischerweise vorne am Client, gRPC hinten zwischen Servern.

KI-generiertDieses Bild wurde mit KI erzeugt · Yves Hoppe / KI / cmt

In der Praxis

Die Last wandert vom Client auf den Server

Jedes Feld im Schema hat einen Resolver, und der weiß nichts davon, dass er innerhalb derselben Abfrage gerade zum fünfzigsten Mal läuft. Eine Liste mit fünfzig Beiträgen und dem jeweiligen Autor erzeugt so eine Abfrage für die Liste und fünfzig weitere für die Autoren. Abhilfe schafft eine Sammelschicht, die diese Einzelzugriffe innerhalb eines Durchlaufs bündelt.

Was bei REST der Cache auf dem Weg erledigt hat, baust du bei GraphQL selbst, denn alle Anfragen gehen als POST an dieselbe Adresse. Dazu kommt, dass eine offene Schnittstelle beliebig tief verschachtelte Abfragen zulässt. Ohne Grenze für Tiefe und Kosten reicht eine einzige Anfrage, um die Datenbank für alle anderen unbrauchbar zu machen.

Die Rechteprüfung sitzt nicht mehr am Endpunkt, sondern gehört an jedes Feld. Wer nur auf der obersten Ebene prüft, gibt über eine Beziehung im Graphen Daten heraus, die der Aufrufer auf dem direkten Weg nie bekommen hätte.

GraphQL lernen

Wie Abfragen, Cache und Komponentenstruktur zusammenspielen, üben die Trainings zum React-Ökosystem an einer laufenden Anwendung.

Wer erst die Gegenseite verstehen will, findet den Vergleich mit klassischen HTTP-Schnittstellen in den Kursen zu Schnittstellen im Web .

Kurse, die GraphQL behandeln

Häufige Fragen

Ersetzt GraphQL meine bestehende REST-API?

Meistens nicht sofort. Der übliche Weg ist eine GraphQL-Schicht vor den vorhandenen Diensten, deren Resolver intern die alten Endpunkte aufrufen. Damit bekommt das Frontend sein Schema, und die Backends bleiben, wo sie sind.

Brauche ich für GraphQL eine bestimmte Frontend-Bibliothek?

Nein, eine Abfrage ist am Ende ein HTTP-Aufruf mit einem Textfeld. Clients wie Apollo oder urql nehmen dir aber Caching, Statusverwaltung und das Zusammenfassen von Abfragen ab, deshalb greifen React-Projekte fast immer dazu.

Wie melde ich Fehler, wenn immer 200 zurückkommt?

Fachliche Fehler gehören in das errors-Feld oder besser als eigene Typen ins Schema, etwa als Union aus Erfolgsfall und Fehlerfall. Dann muss der Client den Fehler behandeln, weil das Schema ihn dazu zwingt.

Persönlich für dich da