GraphQL — was es ist, Abfragesprache und Anwendung in mobilen Projekten

Was ist GraphQL?

GraphQL — ist eine Spezifikation und Laufzeitumgebung für APIs, die dem Client die volle Kontrolle über die empfangenen Daten gibt. Entwickelt von Facebook-Ingenieuren zur Lösung der Probleme der News Feed-Mobilanwendung, wurde die Spezifikation 2015 als offener Standard veröffentlicht. Seit 2018 wird GraphQL von der GraphQL Foundation mit Unterstützung der Linux Foundation und Unternehmen wie Apollo, AWS, GitHub, SAP und anderen verwaltet.

Im Gegensatz zu REST, wo jeder Endpunkt eine feste Datenstruktur zurückgibt, verwendet GraphQL einen einzigen Endpunkt, der eine Abfragezeichenfolge akzeptiert. Der Client beschreibt in der Abfrage, welche Felder er benötigt, und der Server gibt genau diese zurück. Beispielsweise gibt die Abfrage { user(id: "1") { name email } } nur den Namen und die E-Mail des Benutzers zurück, ohne zusätzliche Felder wie address, phone oder createdAt, die in REST abgerufen werden müssten.

GraphQL ist an keine bestimmte Datenbank oder Sprache gebunden. Die Spezifikation definiert nur das Format von Abfragen und Antworten. Es gibt Server-Implementierungen auf Node.js (graphql-js, Apollo Server), Kotlin (graphql-kotlin, Netflix DGS Framework), Python (Graphene, Strawberry), Ruby (graphql-ruby) und anderen Sprachen. Client-Bibliotheken sind für alle wichtigen Plattformen verfügbar, einschließlich Apollo Client für iOS, Android und Web.

Wie GraphQL funktioniert

Die GraphQL-Architektur besteht aus drei Schlüsselkomponenten: Schema, Resolver und der GraphQL-Engine. Das Schema definiert, welche Datentypen verfügbar sind, welche Abfragen ausgeführt werden können und welche Argumente sie akzeptieren. Resolver sind serverseitige Funktionen, die Daten für jedes Schemafeld zurückgeben. Die Engine empfängt die eingehende Abfrage, validiert sie gegen das Schema, ruft die entsprechenden Resolver auf und setzt die Antwort zusammen.

Der Ablauf der Abfrageverarbeitung sieht wie folgt aus:

• Der Client sendet eine POST-Anfrage an /graphql mit einem JSON-Body { "query": "..." }
• Der Server parsed die Abfrage, erstellt einen AST (Abstrakten Syntaxbaum) und validiert ihn gegen das Schema
• Die Engine durchläuft den AST, ruft für jedes Feld Resolver auf und sammelt Daten
• Die Antwort wird im JSON-Format zurückgegeben, das streng der Abfragestruktur entspricht

Der Hauptvorteil der GraphQL-Architektur ist die feldweise Auflösung. In REST erhält der Entwickler entweder alle Felder einer Ressource (möglicherweise mit überflüssigen) oder greift auf Erweiterungen wie ?fields=name,email zurück. In GraphQL ist diese Filterung in die Sprache integriert: Jede Abfrage gibt explizit an, welche Felder benötigt werden, und der Server gibt genau diese zurück. Dies ist besonders wichtig für mobile Anwendungen, wo die Menge der übertragenen Daten direkt die Ladegeschwindigkeit und den Datenverbrauch beeinflusst.

Query, Mutation und Subscription

GraphQL definiert drei Arten von Operationen, die jeweils einem bestimmten Interaktionsszenario entsprechen. Query — zum Lesen von Daten, analog zu GET in REST. Mutation — zum Ändern von Daten (Erstellen, Aktualisieren, Löschen), analog zu POST/PUT/DELETE. Subscription — für Echtzeit-Updates über WebSocket, das in klassischem REST keine direkte Entsprechung hat (zusätzliche Lösungen wie WebSocket oder Server-Sent Events erforderlich).

Die grundlegende Abfragesyntax ist intuitiv:

// Einfache Abfrage mit Argument
query {
    user(id: "42") {
        name
        email
        avatarUrl
    }
}

// Mutation, die geänderte Daten zurückgibt
mutation {
    updateProfile(name: "Ivan") {
        id
        name
        updatedAt
    }
}

// Subscription — hört auf Echtzeit-Updates
subscription {
    newMessage(chatId: "chat_1") {
        id
        text
        sender { name }
    }
}

Query wird parallel ausgeführt — alle Felder auf derselben Ebene werden gleichzeitig geladen. Dies ermöglicht das Laden verwandter Daten (Benutzer und seine Beiträge) in einer einzigen Anfrage ohne mehrere Round-Trips. Mutation wird sequentiell ausgeführt — Mutationen in einer Anfrage werden nacheinander in der Reihenfolge der Deklaration ausgeführt. Subscription stellt eine permanente Verbindung über WebSocket her, über die der Server Daten sendet, wenn ein Ereignis eintritt.

Operationen können Variablen zur Trennung von Daten und Abfrage, Direktiven (@include, @skip) zur bedingten Einbeziehung von Feldern und Fragmente zur Wiederverwendung von Feldsätzen akzeptieren. Diese Fähigkeiten machen GraphQL-Abfragen flexibel und wiederverwendbar, was besonders in großen Projekten mit vielen Bildschirmen und Komponenten wichtig ist.

GraphQL-Schema und Typsystem

Im Kern von GraphQL steht ein Typsystem, das alle möglichen Daten und API-Operationen beschreibt. Das Schema ist eine Beschreibung der Typen, die der Server zurückgeben kann, und der Abfragen, die er akzeptiert. Das Schema wird in der Schema Definition Language (SDL) geschrieben und dient als Vertrag zwischen Client und Server. Der Client kann das Schema durch Introspection erhalten — eine spezielle Abfrage __schema, die eine vollständige Beschreibung der API zurückgibt.

Beispielschema für einen Blog:

// SDL — Schema Definition Language
type User {
    id: ID!
    name: String!
    email: String
    posts: [Post!]!
}

type Post {
    id: ID!
    title: String!
    content: String
    author: User!
}

type Query {
    user(id: ID!): User
    posts(page: Int): [Post!]!
}

Das Ausrufezeichen (!) bedeutet ein Non-Null-Feld — es ist garantiert in der Antwort vorhanden. Eckige Klammern [ ] kennzeichnen eine Liste. GraphQL unterstützt skalare Typen (Int, Float, String, Boolean, ID), Objekttypen, Enum, Union, Interface und Eingabetypen (für Mutationsargumente). Die strenge Typisierung dokumentiert die API selbst und ermöglicht Client-Tools die Codegenerierung: TypeScript-Typen, Kotlin-Datenklassen, Swift-Strukturen.

Introspection ist eine einzigartige GraphQL-Funktion, die in REST fehlt. Der Client kann eine Abfrage an das Schema senden und eine vollständige Beschreibung aller Typen, Felder, Argumente und Direktiven erhalten. Dies ist die Grundlage von Tools wie GraphiQL und Apollo Studio, die automatisch Dokumentation und Autovervollständigung für Entwickler generieren. Introspection ermöglicht auch das Schreiben automatisierter Tests, die die Übereinstimmung des Schemas mit der erwarteten Struktur überprüfen.

GraphQL im Vergleich zu REST

Die Wahl zwischen GraphQL und REST ist eine der wichtigsten Architekturentscheidungen beim Entwurf einer API. Beide Ansätze haben ihre Stärken und Schwächen, und die Wahl hängt von den spezifischen Projektanforderungen ab. REST punktet mit Einfachheit und Universalität, GraphQL mit Flexibilität und Abfrageeffizienz. Sehen wir uns die Vergleichstabelle an.

Der Hauptnachteil von GraphQL ist die Caching-Komplexität. In REST funktioniert HTTP-Caching auf URL-Ebene: Eine Anfrage an /api/users/42 gibt immer dieselbe Struktur zurück, und die Antwort kann per URL zwischengespeichert werden. In GraphQL gehen alle Anfragen an einen einzigen Endpunkt, und die Antwortstruktur hängt vom Anfragekörper ab. Zur Lösung dieses Problems verwendet Apollo Client einen normalisierten Cache auf Client-Seite, der Antworten in einzelne Entitäten nach ID aufteilt und diese beim Empfang neuer Daten automatisch aktualisiert.

Ein weiterer wichtiger Aspekt ist das N+1-Problem. Beim Anfordern verschachtelter Daten (z. B. Benutzerbeiträge und Kommentare zu jedem Beitrag) kann GraphQL eine separate SQL-Abfrage für jedes Listenelement ausführen. Gelöst wird dies mit DataLoader — einem Dienstprogramm zum Bündeln und Zwischenspeichern von Datenbankabfragen, das einzelne Anfragen zu einem Batch zusammenfasst. In REST ist dieses Problem weniger ausgeprägt, da der Entwickler die Antwortstruktur auf Serverseite kontrolliert.

Beispiele für GraphQL-Abfragen

Betrachten wir praktische Beispiele für die Verwendung von GraphQL in einer Kotlin-Mobilanwendung mit Apollo Client. Die Beispiele zeigen typische Szenarien: Laden von Daten für einen Profilbildschirm (query), Erstellen eines neuen Beitrags (mutation) und Abonnieren neuer Kommentare (subscription). Jedes Beispiel enthält sowohl die GraphQL-Abfrage als auch den Client-Code.

Query: Laden eines Profils mit Beiträgen

Eine einzige GraphQL-Abfrage lädt den Benutzer, seine neuesten Beiträge und die Gesamtzahl der Follower. In REST wären dafür mindestens 2-3 Anfragen erforderlich: /users/42, /users/42/posts, /users/42/stats. GraphQL kombiniert sie in einem einzigen Round-Trip und verkürzt so die Ladezeit des Bildschirms bei langsamen Verbindungen.

// GraphQL-Abfrage (in .graphql-Datei)
query ProfileScreen($userId: ID!) {
    user(id: $userId) {
        name
        bio
        avatarUrl
        posts(limit: 10) {
            id
            title
            createdAt
        }
        followersCount
        followingCount
    }
}

// Aufruf auf dem Client (Apollo Client + Kotlin)
val response = apolloClient
    .query(ProfileScreenQuery(userId = "42"))
    .execute()
binding.nameText.text = response.data?.user?.name

Mutation: Erstellen eines neuen Beitrags

Die Mutation erstellt nicht nur eine Ressource, sondern gibt auch ihre aktuellen Daten zur Aktualisierung der Benutzeroberfläche zurück. Das Feld __typename wird von Apollo Client zur Cache-Normalisierung verwendet – der Client aktualisiert automatisch den Post-Eintrag im Cache bei erfolgreicher Mutationsantwort.

// GraphQL-Mutation
mutation CreatePost($input: CreatePostInput!) {
    createPost(input: $input) {
        id
        title
        createdAt
        author {
            id
            name
        }
    }
}

// Mutationsaufruf mit input-Typ
val input = CreatePostInput(
    title = "Neuer Beitrag über GraphQL",
    content = "GraphQL vereinfacht die Arbeit mit API..."
)
val result = apolloClient
    .mutation(CreatePostMutation(input))
    .execute()

Ein wichtiger Vorteil von GraphQL gegenüber REST im Kontext der mobilen Entwicklung ist die automatische Codegenerierung. Apollo Client für Kotlin (Apollo GraphQL) generiert typsichere Klassen aus .graphql-Dateien zur Build-Zeit. Wenn der Server das Schema ändert, wird das Projekt nicht gebaut, bis die Abfragen aktualisiert werden. Dies verhindert Laufzeitfehler, die bei REST typisch sind, wo Änderungen der Antwortstruktur während der Entwicklung unbemerkt bleiben können.

Ökosystem: Apollo, Relay und Werkzeuge

Das GraphQL-Ökosystem umfasst mehrere wichtige Bibliotheken und Tools, die Entwicklung und Betrieb vereinfachen. Apollo Client ist die beliebteste Client-Bibliothek und unterstützt React, iOS, Android und Kotlin Multiplatform. Relay von Facebook ist eine Alternative für React-Anwendungen mit einem einzigartigen Ansatz zur Datenverwaltung und Caching. Die Wahl zwischen Apollo und Relay hängt von der Plattform und den Leistungsanforderungen ab.

Auf der Serverseite führen Apollo Server (Node.js), Netflix DGS Framework (Kotlin/Java) und graphql-ruby. Für die Schemaentwicklung und AbfrageTests wird GraphiQL verwendet — eine interaktive IDE, die in den Browser integriert ist. Apollo Studio bietet Leistungsmetriken, Abfrageverfolgung und Schemaverwaltung für Produktionsumgebungen. Gesondert zu erwähnen ist GraphQL Code Generator — ein Tool, das TypeScript-, Kotlin-, Swift- und Dart-Typen aus einem SDL-Schema generiert.

Für die mobile Entwicklung ist Apollo Kotlin (Apollo GraphQL) von besonderem Interesse — eine vollständig in Kotlin geschriebene Bibliothek mit Unterstützung für Coroutinen, Flow und Multiplatform. Sie ermöglicht die Verwendung einheitlicher GraphQL-Abfragen für Android und iOS in Kotlin-Multiplatform-Projekten. Apollo Kotlin normalisiert den Cache, unterstützt feldbezogene Fehler (Teilfehler) und generiert automatisch Datenmodelle aus .graphql-Dateien. Dies macht GraphQL zur bevorzugten Wahl für große mobile Projekte, bei denen Entwicklungsgeschwindigkeit und Typsicherheit wichtig sind.