Abfragesprache für Schnittstellen

Was ist GraphQL?

Graph Query Language

GraphQL ist eine Abfragesprache für Programmierschnittstellen (APIs) samt Laufzeit auf dem Server. Ein typisiertes Schema legt fest, welche Daten es gibt, und der aufrufende Client benennt in seiner Anfrage genau die Felder, die er braucht, und bekommt auch nur diese zurück.

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 (Linux Foundation)
Aufbau
Ein Endpunkt, ein typisiertes Schema
Verwechselt mit
Graphdatenbanken wie Neo4j

So sieht eine Abfrage aus

Eine GraphQL-Anfrage beschreibt die gewünschte Antwort in ihrer Form. Der Client schickt sie an einen einzigen Endpunkt, meist /graphql per POST, und erhält ein JSON-Objekt, das genau so verschachtelt ist wie die Anfrage. Im Beispiel fragt der Client nach dem Namen eines Benutzers und den Titeln seiner Projekte, und nichts sonst kommt zurück.

# Anfrage
query {
  benutzer(id: "42") {
    name
    projekte {
      titel
    }
  }
}

# Antwort
{
  "data": {
    "benutzer": {
      "name": "Anna",
      "projekte": [{ "titel": "Relaunch" }]
    }
  }
}

Mit REST bräuchte derselbe Bildschirm oft zwei Aufrufe, einen für den Benutzer und einen für seine Projekte, und bekäme dabei alle Felder mit, die der Server standardmäßig liefert. Das Zuviel heißt Overfetching, das Zuwenig mit Folgeaufrufen Underfetching. Beides vermeidet GraphQL.

Schema, Query, Mutation, Resolver

Am Anfang steht das Schema, geschrieben in der Schema Definition Language (SDL). Es beschreibt Typen und Felder, das Ausrufezeichen markiert Pflichtfelder, eckige Klammern Listen. Das Schema ist zugleich Dokumentation und Vertrag: Werkzeuge lesen es über die sogenannte Introspection aus und bieten Autovervollständigung, Prüfung und generierte Typen an.

type Benutzer {
  id: ID!
  name: String!
  projekte: [Projekt!]!
}

type Query {
  benutzer(id: ID!): Benutzer
}

Lesende Anfragen heißen Query, schreibende Mutation, und für laufende Aktualisierungen über eine offene Verbindung gibt es die Subscription. Hinter jedem Feld steht auf dem Server ein Resolver, eine kleine Funktion, die den Wert beschafft. Woher er ihn hat, ist GraphQL egal: aus einer Datenbank, aus einem anderen Dienst oder aus einem Cache. Deshalb lässt sich GraphQL auch als Fassade vor bestehende Systeme legen.

Warum Teams GraphQL einführen

Der übliche Auslöser ist eine App, die für einen einzigen Bildschirm mehrere Endpunkte nacheinander aufrufen muss und dabei Felder mitbekommt, die niemand anzeigt. Gerade bei mobilen Apps mit langsamer Verbindung zählt jeder eingesparte Aufruf. Mit GraphQL wird daraus eine Anfrage, die genau die Felder dieses Bildschirms enthält.

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

GraphQL wurde ab 2012 bei Facebook für die eigenen Apps entwickelt und 2015 als offene Spezifikation veröffentlicht. Heute verantwortet die GraphQL Foundation unter dem Dach der Linux Foundation die Weiterentwicklung. Öffentliche GraphQL-APIs bieten unter anderem GitHub und Shopify an.

Wann sich GraphQL nicht lohnt

Für eine kleine Schnittstelle mit wenigen, stabilen Ressourcen und nur einem Client bringt GraphQL mehr Aufwand als Nutzen. Schema, Resolver, Absicherung gegen teure Abfragen und eigenes Caching sind Arbeit, die sich erst auszahlt, wenn mehrere Clients unterschiedliche Ausschnitte derselben Daten brauchen.

Auch Datei-Uploads, große Downloads und einfache Webhooks laufen über klassische HTTP-Endpunkte meist bequemer. Viele Systeme kombinieren deshalb beides: GraphQL für die Daten des Frontends, REST für alles, was eher Dateien oder Ereignisse sind.

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, denn GraphQL antwortet meist mit 200 und einem errors-Feld.

GraphQL gegen Graphdatenbank

Trotz des Namens ist GraphQL keine Datenbank und keine Abfragesprache für Graphdatenbanken wie Neo4j. Der Graph meint die Beziehungen zwischen den Typen im Schema, die Daten selbst können in jeder beliebigen Datenbank liegen.

GraphQL gegen SQL

SQL fragt Tabellen direkt in der Datenbank ab und kann filtern, gruppieren und verknüpfen, wie es die Anfrage verlangt. GraphQL fragt eine Schnittstelle ab und kann nur das liefern, was Schema und Resolver anbieten.

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

Das bekannteste Problem heißt N+1. Jedes Feld hat einen Resolver, und der weiß nicht, 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 Datenbankabfrage für die Liste und fünfzig weitere für die Autoren. Die Standardantwort ist eine Sammelschicht nach dem Muster von DataLoader, die die Einzelzugriffe innerhalb eines Durchlaufs bündelt.

Weil Clients Abfragen frei zusammenbauen, kann eine tief verschachtelte Anfrage den Server lahmlegen. Üblich sind deshalb eine Grenze für die Verschachtelungstiefe, Kostenbudgets pro Abfrage und im Produktivbetrieb oft nur vorab registrierte Abfragen, sogenannte Persisted Queries. Diese lassen sich dann auch wieder per GET und HTTP-Cache ausliefern, was bei frei formulierten POST-Anfragen kaum greift.

Die Rechteprüfung sitzt nicht mehr am Endpunkt, sondern gehört an jedes Feld oder in die Geschäftslogik darunter. 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.

Häufige Fragen

Wofür steht GraphQL?
QL steht für Query Language, also Abfragesprache. Graph bezieht sich darauf, dass die Typen im Schema wie ein Netz miteinander verbunden sind und eine Abfrage diesen Verbindungen folgt, etwa vom Benutzer zu seinen Projekten und weiter zu deren Mitgliedern.
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 Bibliothek?
Nein, eine Abfrage ist am Ende ein HTTP-Aufruf mit einem Textfeld. Clients wie Apollo Client oder urql nehmen dir aber Caching, Statusverwaltung und das Zusammenfassen von Abfragen ab. Auf dem Server gibt es Implementierungen für praktisch jede Sprache, etwa Apollo Server oder GraphQL Yoga für Node.js.
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.

Passt thematisch dazu

Wie du die Antworten im Frontend absicherst, statt dem Schema blind zu vertrauen, zeigt der Beitrag darüber, wie du Typen aus dem Schema erzeugst und Antworten prüfst.

Persönlich für dich da

Deine Ansprechpartner

Du willst das Thema nicht nur nachschlagen, sondern anwenden können? Wir beraten dich persönlich und kostenlos.

Yves Hoppe

Yves Hoppe

Weiterbildung & Beratung

Ordnet mit dir ein, welcher Kurs zu deinem Vorwissen passt.

Norbert Jansen

Norbert Jansen

Beratung & Inhouse

Plant Inhouse-Trainings, die an euren eigenen Daten und Abläufen ansetzen.

GraphQL im Kurs statt im Lexikon

Nachschlagen bringt dich bis zum Verstehen. Anwenden lernst du an echten Aufgaben.