GraphQL

Was es ist

GraphQL ist eine Abfragesprache für APIs samt der Laufzeitumgebung,
die diese Abfragen auf dem Server ausführt. Der Client sendet ein
Dokument mit genau den gewünschten Feldern. Der Server antwortet mit
entsprechend geformten Daten. Die Spezifikation beschreibt GraphQL
als Sprache und Ausführungsengine für Client-Server-Anwendungen. Sie
hält fest, dass GraphQL 2012 entstand, die Arbeit daran als offenem
Standard 2015 begann und es seit 2019 ein Ergebnis des GraphQL
Specification Project unter der Joint Development Foundation ist.
Die jüngste Veröffentlichung ist die Ausgabe vom September 2025.

Alles beginnt mit dem veröffentlichten Schema eines Dienstes: Typen
mit benannten Feldern, die jeweils wiederum einen eigenen Typ haben.
Die eingebauten Skalartypen sind `Int`, `Float`, `String`, `Boolean`
und `ID`. Ein Dienst kann eigene ergänzen, etwa für eine UUID. Jeder
Typ ist nullable, solange er nicht mit `!` markiert ist. Ein
`String!` kann daher niemals null sein. Listen stehen in eckigen
Klammern: `[LineItem!]!` ist eine stets vorhandene Liste, die
niemals null enthält. Auch das Schema lässt sich abfragen. Über die
Introspektionsfelder `__schema` und `__type` kann ein Client
erfragen, was ein Dienst anbietet. Darauf bauen Entwicklerwerkzeuge
und Clientbibliotheken auf.

Es gibt drei Arten von Operationen. Eine Query ist laut
Spezifikation „ein rein lesender Abruf“, eine Mutation ein
Schreibvorgang mit anschließendem Abruf, eine Subscription eine
langlebige Anfrage, die auf eine Folge von Ereignissen im
Zeitverlauf Daten liefert. Auf dem Server steht hinter jedem Feld
eine Funktion, meist Resolver genannt, die seinen Wert erzeugt. Der
Dienst validiert eine Operation zunächst gegen das Schema. Erst dann
ruft er die Resolver der ausgewählten Felder auf. Die obersten
Felder einer Mutation laufen nacheinander statt parallel. Zwischen
zwei Schreibvorgängen derselben Anfrage kann dadurch keine Race
Condition entstehen.

Die Spezifikation schreibt weder Transport noch
Serialisierungsformat vor. Meist wird HTTP gewählt. Eine GraphQL-API
liegt dann an einer einzigen URL, gewöhnlich mit `/graphql` am Ende,
und antwortet im verbreitetsten Format JSON. Der Client sendet einen
POST, dessen JSON-Body den Abfragetext unter `query` und bei Bedarf
die `variables` enthält. Für Queries darf ein Server auch GET
akzeptieren; eine Mutation muss jedoch immer POST verwenden. Die
Antwort enthält das Ergebnis unter `data`, Fehler unter `errors`.
Die Hinweise der GraphQL Foundation hierzu folgen einer
GraphQL-over-HTTP-Spezifikation, die weiterhin ein Entwurf ist.

Warum es wichtig ist

Bei den meisten HTTP-APIs legt der Server fest, was jeder Endpunkt
zurückgibt. Ein Bildschirm, der den Status einer Bestellung und den
Kundennamen braucht, erhält entweder die ganze Bestellung und den
ganzen Kunden, also mehr als angefragt, oder muss eine Anfrage je
Ressource stellen und die Antworten zusammensetzen. Die
Spezifikation nennt diese Probleme Over-Fetching und Under-Fetching.
GraphQL kehrt die Anordnung um: Der Client fragt auf der Ebene
einzelner Felder und erhält genau diese zurück, keine weiteren. Eine
Anfrage kann zudem Beziehungen von einer Bestellung zu ihren
Positionen und ihrem Kunden verfolgen, weil sie dieselbe Form wie
die erwarteten Daten hat.

Das Typsystem zahlt sich zweimal aus. Jede Operation wird gegen das
Schema validiert, bevor ein Resolver läuft. Ein falsch geschriebener
Feldname oder ein Argument falschen Typs führt deshalb zur
vollständigen Ablehnung, bevor irgendetwas ausgeführt wurde.
Werkzeuge können dieselben Fehler schon beim Schreiben erkennen. Da
ein Client zudem nur die ausgewählten Felder erhält, ist für
bestehende Clients wegen eines neuen Felds keine Anpassung nötig.
Eine API lässt sich so praktikabel ohne Versionsnummern entwickeln:
Ein neues Feld erscheint neben dem alten. Das alte wird mit
`@deprecated` und einer Begründung markiert, bleibt gültig, damit
bestehende Clients nicht ausfallen, und wird entfernt, sobald es
kein Client mehr nutzt.

Die Nachteile sind handfest und entstehen vor allem dadurch, dass
GraphQL HTTP-eigene Mechanismen verlässt. Entitäten werden nicht
mehr durch URLs identifiziert. Alles geht an eine Adresse, meist per
POST, während normalerweise GET-Anfragen standardmäßig als cachebar
gelten. Das Zwischenspeichern durch Intermediäre, das eine REST-API
ohne Zusatzaufwand erhält, muss bewusst neu aufgebaut werden. Der
Statuscode erzählt nicht mehr die ganze Geschichte: Eine Antwort mit
Daten und Fehlern zugleich ist auf HTTP-Ebene weiterhin ein Erfolg.
Der Client stellt nun Anfragen zusammen, die der Server noch nie
gesehen hat. Eine einzige kann daher sehr viel Arbeit verlangen. Den
Server davor zu schützen ist Aufgabe des Dienstes, nicht etwas, das
GraphQL für ihn übernimmt. Resolver pro Feld sind leicht zu
schreiben, führen bei naiver Umsetzung jedoch viele einzelne Aufrufe
an die dahinterliegende Datenbank aus.

Wie es in der Praxis aussieht

Ein kleiner Schemaausschnitt für Bestellungen mit Positionen und
einem Kunden:

```graphql
type Query {
  order(id: ID!): Order
}

type Order {
  id: ID!
  status: String!
  items: [LineItem!]!
  customer: Customer
}

type LineItem {
  name: String!
  quantity: Int!
}

type Customer {
  name: String!
}
```

Ein Bildschirm mit Status, Positionen und Kundenname sendet diese
Operation im Body eines POST an `/graphql`, mit `{"id": "7421"}` als
Variablen:

```graphql
query OrderSummary($id: ID!) {
  order(id: $id) {
    status
    items {
      name
      quantity
    }
    customer {
      name
    }
  }
}
```

Angenommen, Bestellung und Positionen lassen sich auflösen, aber der
Dienst hinter `customer` ist ausgefallen. Die Antwort enthält
weiterhin alles, was erzeugt werden konnte. Das fehlgeschlagene Feld
ist null. Ein Eintrag in `errors` erklärt den Fehler, seine Stelle
im Dokument — Zeile 8, Spalte 5 ist `customer` — und den betroffenen
Pfad in der Antwort:

```json
{
  "data": {
    "order": {
      "status": "open",
      "items": [{ "name": "notebook", "quantity": 2 }],
      "customer": null
    }
  },
  "errors": [
    {
      "message": "Customer service unavailable",
      "locations": [{ "line": 8, "column": 5 }],
      "path": ["order", "customer"]
    }
  ]
}
```

Weil `customer` als nullable deklariert ist, bleibt der Schaden auf
dieses Feld begrenzt. Bei `Customer!` hätte sich der Fehler zum
übergeordneten Feld fortgesetzt und die ganze Bestellung wäre null
zurückgekommen. Und weil `data` nicht null ist, antwortet der Server
trotz Fehler mit einem 2xx-Status: HTTP hat keinen Statuscode für
Teilerfolg. Ein Client, der nur den Statuscode betrachtet, hält
diese Antwort für vollständig.

Das Gegenmodell, bei dem der Server die Form jeder Antwort bestimmt,
setzte ein Projekt im Portfolio dieser Website um. Beim
unveränderten Durchreichen von JSON aus Postgres zur API bauen
PostgreSQL-Funktionen die ganze Antwort als JSON zusammen. Der
Go-Handler leitet sie unverändert weiter. Eine geänderte
Funktionsantwort verändert damit die beim Client ankommenden Daten,
ohne eine Zeile Handlercode anzufassen. Dort hängt das Frontend
direkt von der Datenform der Datenbank ab. In GraphQL benennt der
Client die Felder. Der Server muss jede vom Schema erlaubte
Kombination auflösen können.

Wo es schiefgeht

Ein Feld, tausend Datenbankaufrufe. Resolver sind kleine Funktionen
pro Feld. Ein naiver Dienst ruft sie Objekt für Objekt auf. Eine
Bestellliste mit dem Kunden jeder Bestellung kostet dann einen
Datenbankaufruf für die Liste und einen weiteren pro Bestellung. Die
Hinweise der GraphQL Foundation nennen das N+1-Problem und verweisen
auf Batching: Innerhalb eines kurzen Zeitfensters angeforderte
Ladevorgänge werden gesammelt und als eine Anfrage an die Datenbank
geschickt, etwa mit Facebooks DataLoader.

Eine Anfrage verlangt alles. Weil der Client die Operation schreibt,
kann ein Dokument Freunde von Freunden über viele Ebenen
verschachteln, ein teures Feld unter hundert Aliasen wiederholen
oder viele Operationen in eine Anfrage packen. All das ist gültiges
GraphQL und kann Serverressourcen binden. Die Abwehr liegt beim
Dienst: Listenfelder paginieren, vor der Ausführung Operationen mit
zu großer Tiefe oder Breite ablehnen, Aliasanzahl und Batchgröße
begrenzen. Für feinere Kontrolle erhalten Felder Gewichte.
Operationen mit geschätzten Kosten über dem Budget werden
abgewiesen. Für diese Query Complexity Analysis legt die
Spezifikation selbst keine Regeln fest. Eine API nur für eigene
Clients kann mit vertrauenswürdigen Dokumenten weitergehen:
Ausschließlich vorab gespeicherte und per Hash gefundene Operationen
dürfen dann überhaupt laufen.

200 OK verbirgt den Fehler. Wie im Beispiel können Antworten mit
Fehlern trotzdem einen 2xx-Status tragen. Beim älteren Medientyp
`application/json` gehen die Hinweise weiter: Ein 2xx wird selbst
dann empfohlen, wenn eine gültige Anfrage nicht ausgeführt werden
kann. Manche älteren Server geben sogar bei Validierungsfehlern 2xx
zurück. Der Client und sein Monitoring müssen daher `errors` lesen,
nicht nur den Status. Der neuere Medientyp
`application/graphql-response+json` gibt dem Status wieder
Bedeutung: Eine gültige Anfrage, deren Ausführung scheitert, erhält
dann 4xx oder 5xx. Clients sollten diesen Typ im `Accept`-Header
anfordern.

Das Caching funktioniert nicht mehr. Jede Operation ist ein POST an
dieselbe URL. Caches zwischen Client und Server, einschließlich CDN,
sehen daher eine Adresse und eine Methode, die sie standardmäßig
nicht zwischenspeichern. Queries per GET helfen, aber ein langes
Dokument kann die von Browsern und CDNs akzeptierte URL-Länge
überschreiten. Persistierte Queries lösen beide Probleme: Der Client
sendet einen Hash, über den der Server vor Validierung und
Ausführung das vollständige Dokument nachschlägt. Wo Antworten über
HTTP gecacht werden, dürfen sensible Antworten nur in privaten
Caches oder gar nicht zwischengespeichert werden.

Ein Feld verschwindet. Clients wählen Felder einzeln. Das Entfernen
oder Umbenennen eines Feldes führt daher bei jedem Client, der es
weiterhin auswählt, zum vollständigen Fehlschlag der betroffenen
Operation: Eine Operation mit einem unbekannten Feld scheitert
insgesamt an der Validierung und liefert keinerlei Daten. Die
Spezifikation lässt veraltete Felder gerade deshalb gültig, damit
bestehende Clients nicht ausfallen. Fügen Sie zuerst den Ersatz
hinzu. Markieren Sie das alte Feld mit `@deprecated` und einer
Begründung, die auf das neue verweist. Entfernen Sie es erst, wenn
es nirgends mehr ausgewählt wird.

Weiterführende Lektüre

  * Versionen der GraphQL-Spezifikation — Alle Ausgaben von Juli
2015 bis September 2025 sowie der Arbeitsentwurf: Sprache,
Typsystem, Validierung, Ausführung und Fehler.

  * Bereitstellung über HTTP — Der einzelne Endpunkt, POST und GET,
die beiden Antwortmedientypen und ihre jeweiligen Statuscoderegeln.

  * Leistung — GET für Queries, persistierte Queries, das
N+1-Problem und Batching.

  * Sicherheit — Vertrauenswürdige Dokumente, Grenzen für Tiefe,
Breite und Batches, Query Complexity Analysis sowie Introspektion
und Fehlerdetails in Produktion.

hDiese Seite im Web	URL:https://engineer.company/de/glossary/graphql/	engineer.company	70
