Erfahre, was GraphQL ist, wie Abfragen, Mutations und Schemata funktionieren und wann man es statt REST einsetzen sollte — plus praktische Vor‑ und Nachteile und Beispiele.
GraphQL ist eine Abfragesprache und Laufzeitumgebung für APIs. Einfach gesagt: Es ist eine Möglichkeit für eine App (Web, Mobile oder ein anderer Service), eine API mit einer klaren, strukturierten Anfrage um Daten zu bitten — und der Server liefert eine Antwort, die dieser Anfrage entspricht.
Viele APIs zwingen Clients dazu, das zu akzeptieren, was ein fester Endpoint zurückgibt. Das führt oft zu zwei Problemen:
Mit GraphQL kann der Client genau die Felder anfordern, die er benötigt, nicht mehr und nicht weniger. Das ist besonders hilfreich, wenn verschiedene Bildschirme (oder verschiedene Apps) unterschiedliche „Ausschnitte“ derselben zugrundeliegenden Daten brauchen.
GraphQL sitzt typischerweise zwischen Client‑Apps und deinen Datenquellen. Diese Datenquellen können sein:
Der GraphQL‑Server empfängt eine Abfrage, entscheidet, wie jedes angeforderte Feld aus der richtigen Quelle geholt wird, und stellt dann die finale JSON‑Antwort zusammen.
Stell dir GraphQL vor wie das Bestellen einer maßgeschneiderten Antwort:
GraphQL wird oft missverstanden, daher ein paar Klarstellungen:
Wenn du die Kerndefinition – Abfragesprache + Laufzeitumgebung für APIs – im Kopf behältst, hast du das richtige Fundament für alles Weitere.
GraphQL wurde entwickelt, um ein praktisches Produktproblem zu lösen: Teams verbrannten zu viel Zeit damit, APIs an reale UI‑Bildschirme anzupassen.
Traditionelle endpoint‑basierte APIs zwingen oft die Wahl zwischen dem Ausliefern unnötiger Daten oder zusätzlichen Aufrufen, um die benötigten Daten zu bekommen. Mit wachsendem Produkt zeigt sich diese Reibung als langsamere Seiten, komplizierterer Client‑Code und schmerzhafte Abstimmung zwischen Frontend‑ und Backend‑Teams.
Over‑fetching tritt auf, wenn ein Endpoint ein „vollständiges“ Objekt zurückgibt, obwohl eine Ansicht nur wenige Felder braucht. Eine mobile Profilansicht braucht vielleicht nur Name und Avatar, aber die API liefert Adressen, Einstellungen, Audit‑Felder und mehr. Das verschwendet Bandbreite und kann die User‑Experience verschlechtern.
Under‑fetching ist das Gegenteil: Kein einzelner Endpoint hat alles, was eine Ansicht braucht, also muss der Client mehrere Anfragen stellen und Ergebnisse zusammensetzen. Das erhöht Latenz und die Wahrscheinlichkeit teilweiser Fehler.
Viele REST‑APIs reagieren auf Änderungen, indem sie neue Endpoints hinzufügen oder versionieren (v1, v2, v3). Versionierung kann nötig sein, erzeugt aber langfristigen Wartungsaufwand: Alte Clients nutzen weiterhin alte Versionen, während neue Features woanders entstehen.
GraphQLs Ansatz ist, das Schema durch Hinzufügen von Feldern und Typen zu erweitern, während bestehende Felder stabil bleiben. Das verringert oft den Druck, neue „Versionen“ nur zur Unterstützung neuer UI‑Bedürfnisse zu erstellen.
Moderne Produkte haben selten nur einen Konsumenten. Web, iOS, Android und Partnerintegrationen brauchen alle unterschiedliche Datenformen.
GraphQL wurde so entworfen, dass jeder Client genau die Felder anfordern kann, die er braucht — ohne dass das Backend für jeden Bildschirm oder jedes Gerät einen separaten Endpoint anlegt.
Eine GraphQL‑API wird durch ihr Schema definiert. Denk daran als die Vereinbarung zwischen Server und allen Clients: Es listet, welche Daten existieren, wie sie verbunden sind und was angefragt oder geändert werden kann. Clients raten nicht nach Endpoints — sie lesen das Schema und fragen spezifische Felder an.
Das Schema besteht aus Typen (wie User oder Post) und Feldern (wie name oder title). Felder können auf andere Typen verweisen; so modelliert GraphQL Beziehungen.
Hier ein einfaches Beispiel in Schema Definition Language (SDL):
type User {
id: ID!
name: String!
posts: [Post!]!
}
type Post {
id: ID!
title: String!
body: String
author: User!
comments: [Comment!]!
}
type Comment {
id: ID!
text: String!
author: User!
post: Post!
}
Weil das Schema stark typisiert ist, kann GraphQL eine Anfrage vor ihrer Ausführung validieren. Wenn ein Client ein Feld anfragt, das nicht existiert (z. B. Post.publishDate, wenn das Schema ein solches Feld nicht hat), kann der Server die Anfrage ablehnen oder teil‑erfüllen und klare Fehler zurückgeben — ohne mehrdeutiges „vielleicht funktioniert es“ Verhalten.
Schemata sind so gestaltet, dass sie wachsen können. Du kannst in der Regel neue Felder hinzufügen (z. B. User.bio), ohne bestehende Clients zu brechen, weil Clients nur das bekommen, was sie anfordern. Das Entfernen oder Ändern von Feldern ist sensibler; Teams markieren Felder daher oft zuerst als veraltet (deprecate) und migrieren Clients schrittweise.
Eine GraphQL‑API wird typischerweise über einen einzigen Endpunkt (z. B. /graphql) exponiert. Statt vieler URLs für unterschiedliche Ressourcen (wie /users, /users/123, /users/123/posts) sendest du eine Query an einen Ort und beschreibst genau die Daten, die du zurückhaben willst.
Eine Query ist im Grunde eine „Einkaufsliste“ von Feldern. Du kannst einfache Felder anfragen (z. B. id und name) und gleichzeitig verschachtelte Daten (z. B. die letzten Posts eines Users) in derselben Anfrage — ohne unnötige Felder herunterzuladen.
Hier ein kleines Beispiel:
query GetUserWithPosts {
user(id: "123") {
id
name
posts(limit: 2) {
id
title
}
}
}
GraphQL‑Antworten sind vorhersehbar: das JSON, das du zurückbekommst, spiegelt die Struktur deiner Query wider. Das macht die Frontend‑Arbeit einfacher, weil du nicht raten musst, wo Daten erscheinen oder verschiedene Antwortformate parsen musst.
Eine vereinfachte Antwort könnte so aussehen:
{
"data": {
"user": {
"id": "123",
"name": "Sam",
"posts": [
{ "id": "p1", "title": "Hello GraphQL" },
{ "id": "p2", "title": "Queries in Practice" }
]
}
}
}
Wenn du ein Feld nicht abfragst, ist es nicht enthalten. Fragst du es an, kannst du es an der entsprechenden Stelle erwarten — das macht GraphQL‑Queries zu einem sauberen Weg, genau das zu holen, was jeder Bildschirm oder jede Funktion braucht.
Queries dienen dem Lesen; Mutations sind der Weg, wie du in einer GraphQL‑API Daten änderst — also erstellst, aktualisierst oder löschst.
Die meisten Mutations folgen demselben Muster:
input‑Objekt), z. B. die zu ändernden Felder.GraphQL‑Mutations geben in der Regel absichtlich Daten zurück, statt nur „success: true“. Das Zurückgeben des aktualisierten Objekts (oder mindestens seiner id und wichtiger Felder) hilft der UI:
Ein gängiges Design ist ein „Payload“‑Typ, der sowohl das aktualisierte Entity als auch mögliche Fehler enthält.
mutation UpdateEmail($input: UpdateUserEmailInput!) {
updateUserEmail(input: $input) {
user {
id
email
}
errors {
field
message
}
}
}
Für UI‑getriebene APIs gilt eine gute Regel: Gib zurück, was du brauchst, um den nächsten Zustand zu rendern (z. B. den aktualisierten user plus eventuelle errors). Das hält den Client einfach, vermeidet Rätselraten über Änderungen und macht Fehlerbehandlung benutzerfreundlicher.
Ein GraphQL‑Schema beschreibt, was angefragt werden kann. Resolver beschreiben, wie es tatsächlich geholt wird. Ein Resolver ist eine Funktion, die an ein bestimmtes Feld im Schema gebunden ist. Wenn ein Client dieses Feld anfragt, ruft GraphQL den Resolver auf, um den Wert zu liefern oder zu berechnen.
GraphQL führt eine Abfrage aus, indem es die angeforderte Struktur durchläuft. Für jedes Feld findet es den passenden Resolver und führt ihn aus. Manche Resolver geben einfach eine Eigenschaft eines bereits im Speicher vorhandenen Objekts zurück; andere rufen eine Datenbank, einen anderen Service auf oder kombinieren mehrere Quellen.
Beispiel: Hat dein Schema User.posts, könnte der posts‑Resolver die posts‑Tabelle nach userId abfragen oder einen separaten Posts‑Service kontaktieren.
Resolver sind die Verbindung zwischen Schema und echten Systemen:
Diese Abbildung ist flexibel: Du kannst deine Backend‑Implementierung ändern, ohne die Client‑Query‑Form zu verändern — solange das Schema konsistent bleibt.
Da Resolver pro Feld und pro Listeneintrag ausgeführt werden können, ist es leicht, viele kleine Aufrufe auszulösen (z. B. Posts für 100 Nutzer mit 100 separaten Datenbankabfragen). Das N+1‑Muster kann Antworten verlangsamen.
Gängige Lösungen sind Batching und Caching (z. B. IDs sammeln und in einer Abfrage holen) und bewusstes Fördern bzw. Beschränken verschachtelter Felder, die Clients anfragen dürfen.
Autorisierung wird oft in Resolvern (oder gemeinsamer Middleware) durchgesetzt, weil Resolver wissen, wer anfragt (über den Kontext) und auf welche Daten zugegriffen werden soll. Validierung passiert typischerweise auf zwei Ebenen: GraphQL übernimmt Typ‑/Form‑Validierung automatisch, während Resolver Geschäftsregeln (z. B. „nur Admins dürfen dieses Feld setzen“) durchsetzen.
Eine Überraschung für viele GraphQL‑Neulinge ist, dass eine Anfrage „erfolgreich“ sein kann und trotzdem Fehler enthält. Das liegt daran, dass GraphQL feldorientiert ist: Wenn einige Felder aufgelöst werden können und andere nicht, kannst du partielle Daten erhalten.
Eine typische GraphQL‑Antwort kann sowohl data als auch ein errors‑Array enthalten:
{
"data": {
"user": {
"id": "123",
"email": null
}
},
"errors": [
{
"message": "Not authorized to read email",
"path": ["user", "email"],
"extensions": { "code": "FORBIDDEN" }
}
]
}
Das ist nützlich: Der Client kann weiterhin rendern, was vorhanden ist (z. B. das Benutzerprofil), während er mit dem fehlenden Feld umgeht.
data häufig null.Formuliere Fehlermeldungen für Endnutzer, nicht fürs Debugging. Vermeide das Offenlegen von Stacktraces, Datenbanknamen oder internen IDs. Ein gutes Muster ist:
messageextensions.coderetryable: true)Logge detaillierte Fehler serverseitig mit einer Request‑ID, damit du untersuchen kannst, ohne Interna offenzulegen.
Definiere einen kleinen Fehler‑„Vertrag“, den Web‑ und Mobile‑Apps teilen: gemeinsame extensions.code‑Werte (z. B. UNAUTHENTICATED, FORBIDDEN, BAD_USER_INPUT), Regeln, wann ein Toast gezeigt wird vs. inline Feldfehler, und wie mit partiellen Daten umgegangen wird. Konsistenz verhindert, dass jeder Client eigene Fehlerkonventionen erfindet.
Subscriptions sind GraphQLs Möglichkeit, Clients Daten zu pushen, sobald sie sich ändern, anstatt dass der Client wiederholt nachfragt. Sie werden typischerweise über eine persistente Verbindung geliefert (meist WebSockets), sodass der Server Ereignisse sofort an verbundene Clients senden kann.
Eine Subscription sieht einer Query ähnlich, aber das Ergebnis ist kein einmaliges Response. Es ist ein Strom von Ergebnissen — jedes repräsentiert ein Ereignis.
Unter der Haube „abonniert“ ein Client ein Thema (z. B. messageAdded in einem Chat). Wenn der Server ein Ereignis veröffentlicht, erhalten alle verbundenen Abonnenten eine Nutzlast, die zur Selection Set der Subscription passt.
Subscriptions eignen sich, wenn Änderungen sofort erwartet werden:
Beim Polling fragt der Client alle N Sekunden „Gibt es Neues?“. Das ist einfach, kann aber viele Anfragen verschwenden (vor allem wenn sich nichts ändert) und wirkt verzögert.
Bei Subscriptions sagt der Server „Hier ist das Update“ sofort. Das reduziert unnötigen Traffic und verbessert die gefühlte Geschwindigkeit — auf Kosten offener Verbindungen und real‑time Infrastrukturmanagement.
Subscriptions sind nicht immer die richtige Wahl. Wenn Updates selten, nicht zeitkritisch oder leicht zu bündeln sind, reicht Polling oder ein nach Benutzeraktion ausgelöster Refetch oft aus.
Sie erhöhen auch den operativen Aufwand: Skalierung der Verbindungen, Auth für lang laufende Sessions, Retries und Monitoring. Gute Regel: Nutze Subscriptions nur, wenn Echtzeit ein Produkt‑Requirement ist, nicht nur ein Nice‑to‑Have.
GraphQL wird oft als „Power für den Client“ beschrieben, aber diese Macht hat Kosten. Die Kenntnis der Tradeoffs hilft zu entscheiden, wann GraphQL passt — und wann es Overhead bringt.
Der größte Gewinn ist flexibles Daten‑Fetching: Clients können genau die Felder anfordern, die sie brauchen, was Over‑fetching reduzieren und UI‑Änderungen beschleunigen kann.
Ein weiterer Vorteil ist der starke Vertrag durch ein GraphQL‑Schema. Das Schema wird zur Single Source of Truth für Typen und verfügbare Operationen, was Zusammenarbeit und Tooling verbessert.
Teams sehen oft bessere Produktivität auf Client‑Seite, weil Frontend‑Entwickler iterieren können, ohne auf neue Endpoint‑Varianten warten zu müssen; Tools wie Apollo Client können Typen generieren und das Daten‑Fetching vereinfachen.
GraphQL kann Caching komplizierter machen. Bei REST ist Caching oft „pro URL“. Bei GraphQL teilen viele Queries denselben Endpoint, daher basieren Caching‑Strategien auf Query‑Shapes, normalisierten Caches und sorgfältiger Server/Client‑Konfiguration.
Serverseitig gibt es Performance‑Fallstricke. Eine scheinbar kleine Query kann viele Backend‑Aufrufe auslösen, wenn Resolver nicht bedacht implementiert sind (Batching, N+1 vermeiden, teure Felder kontrollieren).
Es gibt außerdem eine Lernkurve: Schemata, Resolver und Client‑Pattern sind für Teams, die an endpointbasierte APIs gewöhnt sind, neu.
Weil Clients viel anfragen können, sollten GraphQL‑APIs Tiefe‑ und Komplexitätslimits durchsetzen, um missbräuchliche oder versehentlich „zu große“ Anfragen zu verhindern.
Authentifizierung und Autorisierung sollten pro Feld durchgesetzt werden, nicht nur auf Routen‑Level, da unterschiedliche Felder unterschiedliche Zugriffsregeln haben können.
Operativ solltest du in Logging, Tracing und Monitoring investieren, das GraphQL versteht: Operation‑Namen, Variablen (vorsichtig), Resolver‑Laufzeiten und Fehlerquoten tracken, damit du langsame Queries und Regressionen früh erkennst.
GraphQL und REST helfen beide Apps bei der Kommunikation mit Servern, aber sie strukturieren dieses Gespräch unterschiedlich.
REST ist ressourcenbasiert. Daten holst du über mehrere Endpoints (URLs), die „Dinge“ repräsentieren wie /users/123 oder /orders?userId=123. Jeder Endpoint liefert eine vom Server festgelegte Struktur.
REST nutzt außerdem HTTP‑Semantik: Methoden wie GET/POST/PUT/DELETE, Statuscodes und Caching‑Regeln. Das macht REST natürlich, wenn du einfache CRUD‑Operationen machst oder stark auf Browser/Proxy‑Caches angewiesen bist.
GraphQL ist schema‑basiert. Anstelle vieler Endpoints hast du meist einen Endpunkt, und der Client sendet eine Query, die die gewünschten Felder beschreibt. Der Server validiert gegen das GraphQL‑Schema und liefert eine Antwort, die zur Abfrage passt.
Diese „client‑gesteuerte Auswahl“ ist der Grund, warum GraphQL Over‑ und Under‑fetching reduzieren kann — besonders für UI‑Bildschirme, die Daten aus mehreren miteinander verbundenen Modellen benötigen.
REST passt häufig besser, wenn:
Viele Teams mischen beides:
Die praktische Frage ist nicht „Was ist besser?“, sondern „Was passt für diesen Anwendungsfall mit dem geringsten Aufwand?".
Eine GraphQL‑API zu entwerfen ist am einfachsten, wenn du sie als Produkt für die Bildschirmbauer behandelst, nicht als Abbild deiner Datenbank. Fang klein an, validiere mit echten Use Cases und erweitere bei Bedarf.
Liste deine wichtigen Screens (z. B. „Produktliste“, „Produktdetails“, „Checkout“). Schreib für jeden Screen die exakten Felder auf, die er braucht, und welche Interaktionen unterstützt werden.
Das hilft, „God‑Queries“ zu vermeiden, Over‑fetching zu reduzieren und klarzustellen, wo Filter, Sortierung und Pagination nötig sind.
Definiere zuerst deine Kerntypen (z. B. User, Product, Order) und deren Beziehungen. Dann füge hinzu:
addToCart, placeOrder)Bevorzuge sprechende, business‑nahe Namen statt datenbanknaher Namen. „placeOrder“ kommuniziert die Absicht besser als „createOrderRecord".
Halte die Namensgebung konsistent: Singular für Einzelobjekte (product), Plural für Collections (products). Bei Pagination wählst du meist eine der beiden Varianten:
Entscheide dich früh, weil das die Struktur deiner API‑Responses prägt.
GraphQL unterstützt Beschreibungen direkt im Schema — nutze sie für Felder, Argumente und Randfälle. Ergänze ein paar Copy‑Paste‑Beispiele in deinen Docs (inkl. Pagination und häufigen Fehlerfällen). Ein gut beschriebenes Schema macht Introspection und API‑Explorer deutlich nützlicher.
Mit GraphQL anzufangen heißt meist, ein paar gut unterstützte Tools auszuwählen und einen verlässlichen Workflow einzurichten. Du musst nicht alles auf einmal übernehmen — bring eine Query end‑to‑end zum Laufen und baue darauf auf.
Wähle einen Server basierend auf deinem Stack und wie viel „Batterien inklusive“ du willst:
Ein praktischer erster Schritt: Definiere ein kleines Schema (ein paar Typen + eine Query), implementiere Resolver und verbinde eine echte Datenquelle (auch wenn es zunächst eine stub‑in‑memory Liste ist).
Wenn du schneller von Idee zu funktionsfähiger API kommen willst, können Plattformen zum Vibe‑Coding wie Koder.ai helfen, ein kleines Full‑Stack‑App‑Gerüst zu erzeugen (React Frontend, Go + PostgreSQL Backend) und GraphQL Schema/Resolver interaktiv zu iterieren — danach kannst du den Quellcode exportieren und selbst weiter pflegen.
Auf dem Frontend hängt die Wahl oft davon ab, ob du stark strukturierte Konventionen oder Flexibilität willst:
Wenn du von REST migrierst, starte damit, GraphQL für einen Bildschirm oder ein Feature zu nutzen und lass REST für den Rest, bis sich der Ansatz bewährt hat.
Behandle dein Schema wie einen API‑Vertrag. Nützliche Testschichten sind:
Zur Vertiefung fahre mit folgendem Artikel fort:
GraphQL ist eine Abfragesprache und Laufzeitumgebung für APIs. Clients senden eine Abfrage, die genau die Felder beschreibt, die sie benötigen, und der Server liefert eine JSON-Antwort, die dieser Struktur entspricht.
Man kann es am besten als Schicht zwischen Clients und einer oder mehreren Datenquellen begreifen (Datenbanken, REST-Services, Drittanbieter‑APIs, Microservices).
GraphQL hilft vor allem bei:
Indem der Client nur bestimmte Felder (auch verschachtelte) anfordert, kann GraphQL überflüssige Datenübertragung reduzieren und den Client-Code vereinfachen.
GraphQL ist kein:
Behandle es als API‑Vertrag + Ausführungsengine, nicht als Speicher- oder Performance‑Wunder.
Die meisten GraphQL‑APIs bieten einen einzigen Endpunkt (häufig /graphql). Statt vieler URLs sendest du unterschiedliche Operationen (Queries/Mutations) an diesen einen Endpunkt.
Praktische Konsequenz: Caching und Observability orientieren sich oft an Operationsname + Variablen, nicht an der URL.
Das Schema ist der API‑Vertrag. Es definiert:
User, Post)User.name)User.posts)Da es ist, kann der Server Abfragen vor der Ausführung validieren und klare Fehler zurückgeben, wenn Felder fehlen oder falsch sind.
Queries sind Leseoperationen. Du gibst an, welche Felder du brauchst, und die Antwort‑JSON spiegelt die Struktur der Abfrage wider.
Tipps:
query GetUserWithPosts) für Debugging und Monitoring.posts(limit: 2)).Mutations sind Schreiboperationen (create/update/delete). Üblicher Ablauf:
input‑Objekt wird gesendetDaten zurückzugeben (nicht nur success: true) hilft der UI, sofort zu aktualisieren und Caches konsistent zu halten.
Resolver sind feld‑spezifische Funktionen, die bestimmen, wie GraphQL ein Feld tatsächlich erhält oder berechnet.
In der Praxis können Resolver:
Autorisierung wird oft in Resolvern (oder gemeinsamem Middleware) durchgesetzt, weil sie wissen, wer was anfragt.
Leicht entsteht ein N+1‑Problem (z. B. Posts für 100 Nutzer jeweils separat laden).
Gängige Gegenmaßnahmen:
Miss die Resolver‑Dauer und achte auf wiederholte Downstream‑Aufrufe innerhalb einer Anfrage.
GraphQL kann teilweise Daten zusammen mit einem errors‑Array zurückgeben. Das passiert, wenn einige Felder erfolgreich aufgelöst werden und andere fehlschlagen (z. B. fehlende Berechtigung oder Timeout).
Gute Praxis:
message‑Texte nutzenextensions.code‑Werte (z. B. FORBIDDEN, BAD_USER_INPUT)Clients sollten entscheiden, wann partielle Daten angezeigt werden und wann die Operation als gescheitert gilt.