REST API vs. GraphQL: Welche Schnittstelle passt zu deiner Architektur?

Du stehst vor einer Architekturentscheidung, die dein Projekt auf Jahre hinaus beeinflussen wird: REST API oder GraphQL? Beide Technologien haben sich in der Praxis bewaehrt, beide haben leidenschaftliche Befuerworter — und beide haben ihre Tuecken. Doch anstatt einem Hype zu folgen, solltest du die Entscheidung auf Basis deiner konkreten Anforderungen treffen.

In diesem ausfuehrlichen Vergleich analysieren wir REST und GraphQL aus jeder relevanten Perspektive: Architektur, Performance, Developer Experience, Caching, Sicherheit und Skalierbarkeit. Mit echten Code-Beispielen, einer Vergleichstabelle und einer Entscheidungsmatrix, die dir hilft, die richtige Wahl fuer dein naechstes Projekt zu treffen.

1. Grundlagen: Was sind REST und GraphQL?

REST — Representational State Transfer

REST ist ein Architekturstil fuer verteilte Systeme, der 2000 von Roy Fielding in seiner Dissertation beschrieben wurde. Das Kernprinzip: Jede Ressource hat eine eindeutige URL, und du interagierst mit ihr ueber standardisierte HTTP-Methoden (GET, POST, PUT, DELETE). REST ist kein Protokoll und kein Framework — es ist ein Set von Designprinzipien, die auf dem bestehenden HTTP-Protokoll aufbauen.

Ein REST-API organisiert Daten in Ressourcen. Jede Ressource hat einen eindeutigen Endpunkt, und die HTTP-Methode bestimmt die Aktion. Wenn du GET /api/users/42 aufrufst, bekommst du den Benutzer mit der ID 42 zurueck. Einfach, vorhersehbar und seit ueber 20 Jahren bewaehrt.

Die sechs REST-Constraints — Client-Server, Stateless, Cacheable, Uniform Interface, Layered System und Code on Demand — sorgen dafuer, dass REST-APIs skalierbar, zuverlaessig und entkoppelt sind. In der Praxis halten sich allerdings die wenigsten APIs strikt an alle sechs Prinzipien, weshalb man haeufig von "RESTful" APIs spricht.

GraphQL — Eine Abfragesprache fuer deine API

GraphQL wurde 2012 intern bei Facebook entwickelt und 2015 als Open-Source-Projekt veroeffentlicht. Der Ausloeser: Facebooks mobile Apps brauchten eine effizientere Moeglichkeit, Daten vom Server zu laden. Mit REST mussten sie fuer eine einzige Ansicht oft zehn oder mehr Requests absetzen — auf mobilen Netzwerken ein Performance-Killer.

GraphQL loest dieses Problem radikal anders als REST: Statt vieler fest definierter Endpunkte gibt es genau einen Endpunkt (POST /graphql). Der Client beschreibt in einer Query exakt, welche Daten er braucht — nicht mehr und nicht weniger. Der Server liefert genau diese Struktur zurueck.

Das GraphQL-Typsystem definiert ein Schema, das als Vertrag zwischen Client und Server fungiert. Jedes Feld, jeder Typ und jede Beziehung ist explizit beschrieben. Das macht GraphQL selbstdokumentierend und erleichtert die Zusammenarbeit zwischen Frontend- und Backend-Teams erheblich.

2. Kernunterschiede im Detail

Um REST und GraphQL fundiert vergleichen zu koennen, schauen wir uns die wichtigsten Kriterien im direkten Vergleich an. Die folgende Tabelle gibt dir einen schnellen Ueberblick, bevor wir ins Detail gehen:

Wie du siehst, gibt es keinen klaren "Gewinner" — jede Technologie hat ihre Staerken in bestimmten Bereichen. Die Entscheidung haengt davon ab, welche Kriterien fuer dein Projekt am wichtigsten sind.

3. REST API: Staerken, Schwaechen und ideale Use Cases

Staerken von REST

• Einfachheit: REST baut auf HTTP auf, das jeder Entwickler kennt. Du brauchst keine spezielle Bibliothek — ein curl-Befehl oder ein Browser genuegen.
• Caching: HTTP-Caching ist ein Geschenk. CDNs, Browser-Caches, Reverse Proxies — alles versteht HTTP-Cache-Header out of the box. Bei datenintensiven Anwendungen kann das die Last auf dein Backend um 80-90% reduzieren.
• Mature Ecosystem: REST-APIs gibt es seit ueber 20 Jahren. Die Tools, Best Practices und das Community-Wissen sind enorm.
• Statuscodes: HTTP-Statuscodes kommunizieren den Zustand einer Anfrage eindeutig. Ein 404 ist ein 404 — egal ob du Postman, curl oder einen Browser nutzt.
• File Handling: Datei-Uploads und -Downloads funktionieren mit REST nativ ueber Multipart-Requests und Streaming.

Schwaechen von REST

• Over-Fetching: Du bekommst immer die gesamte Ressource, auch wenn du nur zwei Felder brauchst. Bei mobilen Clients mit begrenzter Bandbreite ist das ein echtes Problem.
• Under-Fetching: Fuer eine komplexe Ansicht brauchst du oft Daten aus mehreren Ressourcen. Das bedeutet mehrere sequenzielle Requests — und jeder fuegt Latenz hinzu.
• Endpunkt-Explosion: Je komplexer deine Anwendung, desto mehr Endpunkte brauchst du. Irgendwann hast du /users, /users/:id, /users/:id/posts, /users/:id/posts/:postId/comments — und die Dokumentation waechst mit.
• Versionierung: Wenn sich deine API aendert, brauchst du Versionierung. /v1/ und /v2/ parallel zu betreiben ist aufwaendig und fehleranfaellig.

Code-Beispiel: Express REST Endpoint

Hier ist ein typischer REST-Endpunkt mit Express.js, der eine Benutzer-Ressource mit zugehoerigen Projekten bereitstellt:

// server.js – REST API mit Express
import express from 'express';

const app = express();
app.use(express.json());

// ── GET /api/users ─────────────────────────────
// Alle Benutzer abrufen (mit optionalem Filtering)
app.get('/api/users', async (req, res) => {
  try {
    const { role, limit = 20, offset = 0 } = req.query;

    const filters = {};
    if (role) filters.role = role;

    const users = await db.users.findMany({
      where: filters,
      take: Number(limit),
      skip: Number(offset),
      select: {
        id: true,
        name: true,
        email: true,
        role: true,
        createdAt: true,
      },
    });

    const total = await db.users.count({ where: filters });

    res.json({
      data: users,
      meta: {
        total,
        limit: Number(limit),
        offset: Number(offset),
      },
    });
  } catch (error) {
    console.error('Fehler beim Abrufen der Benutzer:', error);
    res.status(500).json({ error: 'Interner Serverfehler' });
  }
});

// ── GET /api/users/:id ─────────────────────────
// Einzelnen Benutzer mit Projekten abrufen
app.get('/api/users/:id', async (req, res) => {
  try {
    const user = await db.users.findUnique({
      where: { id: req.params.id },
      include: {
        projects: {
          select: {
            id: true,
            title: true,
            status: true,
          },
        },
      },
    });

    if (!user) {
      return res.status(404).json({ error: 'Benutzer nicht gefunden' });
    }

    // Cache fuer 5 Minuten
    res.set('Cache-Control', 'public, max-age=300');
    res.json({ data: user });
  } catch (error) {
    console.error('Fehler beim Abrufen des Benutzers:', error);
    res.status(500).json({ error: 'Interner Serverfehler' });
  }
});

// ── POST /api/users ────────────────────────────
// Neuen Benutzer anlegen
app.post('/api/users', async (req, res) => {
  try {
    const { name, email, role } = req.body;

    if (!name || !email) {
      return res.status(400).json({
        error: 'Name und E-Mail sind erforderlich',
      });
    }

    const user = await db.users.create({
      data: { name, email, role: role || 'member' },
    });

    res.status(201).json({ data: user });
  } catch (error) {
    if (error.code === 'P2002') {
      return res.status(409).json({
        error: 'Ein Benutzer mit dieser E-Mail existiert bereits',
      });
    }
    res.status(500).json({ error: 'Interner Serverfehler' });
  }
});

app.listen(3000, () => {
  console.log('REST API laeuft auf Port 3000');
});

Ideale Use Cases fuer REST

• Oeffentliche APIs mit breitem Consumer-Spektrum (Drittanbieter, Partner)
• Content-Delivery und Medien-Streaming (starkes HTTP-Caching)
• Einfache CRUD-Anwendungen mit klar definierten Ressourcen
• Microservices-Kommunikation (Service-to-Service)
• APIs, die von vielen unterschiedlichen Clients konsumiert werden (IoT, Mobile, Web)

4. GraphQL: Staerken, Schwaechen und ideale Use Cases

Staerken von GraphQL

• Praeziser Datenabruf: Der Client bekommt exakt die Daten, die er braucht — kein Byte mehr, kein Byte weniger. Das spart Bandbreite und verbessert die Performance auf mobilen Geraeten erheblich.
• Ein Request fuer alles: Statt fuenf sequenzieller REST-Calls kannst du mit einer einzigen GraphQL-Query alle benoetigten Daten auf einmal abrufen. Das reduziert die Latenz drastisch.
• Typsystem und Schema: Das Schema ist ein Vertrag zwischen Frontend und Backend. Es ist selbstdokumentierend, introspektierbar und erzwingt Typsicherheit zur Compile-Zeit.
• Schema-Evolution: Statt Versionierung nutzt GraphQL Deprecation. Alte Felder werden als veraltet markiert, neue Felder hinzugefuegt. Kein Breaking Change, keine parallelen API-Versionen.
• Developer Experience: Tools wie GraphiQL und Apollo Studio bieten Autovervollstaendigung, Inline-Dokumentation und Query-Validierung direkt in der IDE.

Schwaechen von GraphQL

• Caching-Komplexitaet: Da alle Requests an denselben Endpunkt gehen (POST /graphql), funktioniert HTTP-Caching nicht out of the box. Du brauchst normalisierte Client-Caches (Apollo Cache, urql) oder serverseitige Loesungen.
• N+1 Problem: Ohne DataLoader fuehrt eine verschachtelte Query schnell zu Hunderten von Datenbankabfragen. Das N+1-Problem muss aktiv geloest werden.
• Sicherheit: Da der Client die Queries kontrolliert, musst du dich gegen uebermaeßig komplexe oder tief verschachtelte Queries schuetzen (Query-Depth-Limiting, Complexity-Analysis).
• Lernkurve: Schema-Design, Resolver-Architektur, DataLoader, Subscriptions — GraphQL hat eine steilere Lernkurve als REST.
• File Uploads: GraphQL hat keinen nativen Support fuer Datei-Uploads. Du brauchst die multipart-request-Spezifikation oder einen separaten REST-Endpunkt.

Code-Beispiel: GraphQL Schema und Resolver

Hier dasselbe Benutzer-Projekt-Szenario als GraphQL-API mit Apollo Server:

// schema.graphql – GraphQL Typdefinitionen
type User {
  id: ID!
  name: String!
  email: String!
  role: Role!
  projects: [Project!]!
  createdAt: DateTime!
}

type Project {
  id: ID!
  title: String!
  status: ProjectStatus!
  owner: User!
  tasks: [Task!]!
  createdAt: DateTime!
}

type Task {
  id: ID!
  title: String!
  completed: Boolean!
  assignee: User
}

enum Role {
  ADMIN
  MEMBER
  VIEWER
}

enum ProjectStatus {
  ACTIVE
  ARCHIVED
  DRAFT
}

type Query {
  # Einzelnen Benutzer abrufen
  user(id: ID!): User

  # Benutzer filtern und paginieren
  users(
    role: Role
    limit: Int = 20
    offset: Int = 0
  ): UserConnection!

  # Projekt-Details
  project(id: ID!): Project
}

type UserConnection {
  nodes: [User!]!
  totalCount: Int!
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): Boolean!
}

input CreateUserInput {
  name: String!
  email: String!
  role: Role = MEMBER
}

input UpdateUserInput {
  name: String
  email: String
  role: Role
}

// resolvers.js – GraphQL Resolver mit DataLoader
import DataLoader from 'dataloader';

// DataLoader verhindert das N+1 Problem
const createLoaders = () => ({
  projectsByUser: new DataLoader(async (userIds) => {
    const projects = await db.projects.findMany({
      where: { ownerId: { in: userIds } },
    });
    // Gruppiere Projekte nach User-ID
    return userIds.map((id) =>
      projects.filter((p) => p.ownerId === id)
    );
  }),

  tasksByProject: new DataLoader(async (projectIds) => {
    const tasks = await db.tasks.findMany({
      where: { projectId: { in: projectIds } },
    });
    return projectIds.map((id) =>
      tasks.filter((t) => t.projectId === id)
    );
  }),
});

export const resolvers = {
  Query: {
    user: async (_, { id }) => {
      return db.users.findUnique({ where: { id } });
    },

    users: async (_, { role, limit, offset }) => {
      const where = role ? { role } : {};
      const [nodes, totalCount] = await Promise.all([
        db.users.findMany({ where, take: limit, skip: offset }),
        db.users.count({ where }),
      ]);
      return { nodes, totalCount };
    },

    project: async (_, { id }) => {
      return db.projects.findUnique({ where: { id } });
    },
  },

  // Field-Level Resolver mit DataLoader
  User: {
    projects: (user, _, { loaders }) => {
      return loaders.projectsByUser.load(user.id);
    },
  },

  Project: {
    owner: (project) => {
      return db.users.findUnique({
        where: { id: project.ownerId },
      });
    },
    tasks: (project, _, { loaders }) => {
      return loaders.tasksByProject.load(project.id);
    },
  },

  Mutation: {
    createUser: async (_, { input }) => {
      return db.users.create({ data: input });
    },
    updateUser: async (_, { id, input }) => {
      return db.users.update({ where: { id }, data: input });
    },
    deleteUser: async (_, { id }) => {
      await db.users.delete({ where: { id } });
      return true;
    },
  },
};

Beachte den entscheidenden Unterschied: Bei REST brauchst du separate Endpunkte fuer Users und Projects. Bei GraphQL definiert der Client in seiner Query, wie tief er in die Datenstruktur eintauchen will. Ein Frontend-Entwickler kann genau die Felder anfordern, die er fuer seine Komponente braucht — ohne dass das Backend angepasst werden muss.

Ideale Use Cases fuer GraphQL

• Mobile Apps mit begrenzter Bandbreite (praeziser Datenabruf)
• Komplexe UIs mit vielen verschachtelten Datenbeziehungen (Dashboards, Social-Media-Feeds)
• Mehrere Clients mit unterschiedlichen Datenanforderungen (Web, Mobile, Smartwatch)
• Rapid Prototyping und schnelle Feature-Entwicklung (Frontend unabhaengig vom Backend)
• Anwendungen mit Echtzeit-Anforderungen (Subscriptions)

5. Performance-Vergleich: Over-Fetching, N+1 und Caching

Over-Fetching: Der stille Performance-Killer

Stell dir vor, dein Frontend zeigt eine Benutzerliste mit Name und Avatar. Der REST-Endpunkt GET /api/users liefert aber fuer jeden Benutzer 30 Felder zurueck: E-Mail, Adresse, Telefonnummer, Praeferenzen, letzte Login-Zeit und vieles mehr. Das ist Over-Fetching — du laeadst Daten, die du nicht brauchst.

Bei einer Liste mit 50 Benutzern kann das schnell 200 KB unnuetze Daten bedeuten. Auf einem mobilen 3G-Netzwerk sind das spuerbare 2-3 Sekunden zusaetzliche Ladezeit. GraphQL loest dieses Problem elegant: Du fragst nur name und avatarUrl an und bekommst exakt das zurueck.

REST bietet Workarounds wie ?fields=name,avatarUrl (Sparse Fieldsets), aber das muss aktiv implementiert werden und ist kein Standard. In GraphQL ist der praezise Datenabruf das Kernkonzept.

Under-Fetching und die Request-Kaskade

Das Gegenteil von Over-Fetching: Du brauchst mehr Daten, als ein einzelner Endpunkt liefert. Fuer ein Benutzerprofil mit Projekten und deren Tasks brauchst du mit REST typischerweise drei Requests:

1. GET /api/users/42 — Benutzerdaten laden
2. GET /api/users/42/projects — Projekte des Benutzers laden
3. GET /api/projects/7/tasks — Tasks pro Projekt laden (pro Projekt ein Request!)

Bei fuenf Projekten sind das bereits sieben sequenzielle Requests. Mit GraphQL holst du alles in einem einzigen Request:

# Eine Query statt sieben REST-Requests
query UserProfile {
  user(id: "42") {
    name
    email
    avatarUrl
    projects {
      title
      status
      tasks {
        title
        completed
        assignee {
          name
        }
      }
    }
  }
}

Das N+1 Problem bei GraphQL

GraphQL ist nicht ohne eigene Performance-Fallen. Wenn ein Resolver fuer jedes Listenelement eine separate Datenbankabfrage ausfuehrt, entsteht das beruechtigte N+1 Problem: Ein Request fuer die Liste (1) plus ein Request pro Element (N).

Die Loesung heisst DataLoader — ein Batching-Mechanismus, der alle individuellen Abfragen innerhalb eines Ticks zu einer einzigen Batch-Abfrage zusammenfasst. Statt 50 einzelner SELECT * FROM projects WHERE user_id = ? wird ein einziges SELECT * FROM projects WHERE user_id IN (?, ?, ?, ...) ausgefuehrt. Das Codebeispiel im Resolver-Abschnitt oben zeigt genau dieses Pattern.

Caching-Strategien im Vergleich

REST profitiert massiv von HTTP-Caching. CDNs, Browser und Reverse Proxies verstehen Cache-Control-Header nativ. Ein GET /api/products/42 mit Cache-Control: public, max-age=3600 wird automatisch eine Stunde lang gecacht — auf jeder Ebene des Netzwerks.

GraphQL hat es hier schwerer: Alle Requests sind POST-Requests an denselben Endpunkt, mit unterschiedlichem Body. HTTP-Caching greift nicht. Stattdessen nutzt man normalisierte Client-Caches (Apollo Client, urql) oder serverseitige Loesungen wie Persisted Queries, die eine Query einem Hash zuordnen und ueber GET-Requests cachefaehig machen.

Fuer read-heavy Anwendungen mit oeffentlichen Daten (Content-Websites, E-Commerce-Kataloge) ist REST mit HTTP-Caching klar im Vorteil. Fuer personalisierte, dynamische Anwendungen (Dashboards, Social Apps) ist der Unterschied geringer, weil dort ohnehin wenig gecacht werden kann.

6. Entscheidungsmatrix: Welche Technologie wann?

Die folgende Entscheidungshilfe fuehrt dich durch die wichtigsten Fragen, die du bei der Wahl zwischen REST und GraphQL beantworten solltest:

Entscheidungsbaum: REST API vs. GraphQL
========================================

Wie viele verschiedene Clients nutzen die API?
│
├── Ein Client (z.B. nur eine Web-App)
│   │
│   ├── Sind die Datenbeziehungen komplex und verschachtelt?
│   │   ├── JA ──────────────▶ GraphQL
│   │   └── NEIN
│   │       │
│   │       └── Ist HTTP-Caching ein kritischer Faktor?
│   │           ├── JA ──────▶ REST
│   │           └── NEIN ────▶ Beide geeignet (Teamkompetenz entscheidet)
│   │
│   └── Braucht der Client Echtzeit-Updates?
│       ├── JA ──────────────▶ GraphQL (Subscriptions)
│       └── NEIN ────────────▶ REST (einfacher)
│
├── Mehrere Clients mit unterschiedlichen Datenanforderungen
│   │   (z.B. Web-App + Mobile + Smartwatch)
│   │
│   └── ──────────────────────▶ GraphQL (starker Vorteil)
│
└── Oeffentliche API fuer Drittanbieter
    │
    └── ──────────────────────▶ REST (niedrigere Einstiegshuerde)


Weitere Faktoren:
─────────────────
• Team hat REST-Erfahrung, kein GraphQL-Know-how?
  → REST (Lernkurve nicht unterschaetzen)

• Microservices mit Service-to-Service-Kommunikation?
  → REST oder gRPC (GraphQL ist fuer Client-Server optimiert)

• Hohe Datenvolumen, starke Caching-Anforderungen?
  → REST (HTTP-Caching ist unschlagbar)

• Schnell wachsende Anwendung mit vielen neuen Features?
  → GraphQL (Frontend unabhaengig vom Backend)

Diese Matrix ist natuerlich eine Vereinfachung. In der Realitaet spielen viele weitere Faktoren eine Rolle: vorhandenes Team-Wissen, bestehende Infrastruktur, Time-to-Market-Anforderungen und langfristige Wartbarkeit. Aber sie gibt dir einen soliden Ausgangspunkt fuer die Diskussion.

"Waehle nicht die Technologie, die gerade trendet — waehle die Technologie, die dein Team produktiv macht und deine Anforderungen am besten abdeckt."

7. Hybrid-Ansatz, Migration und Fazit

Der Hybrid-Ansatz: Das Beste aus beiden Welten

In der Praxis musst du dich nicht fuer eine Technologie entscheiden. Viele erfolgreiche Architekturen kombinieren REST und GraphQL — und das ist oft die cleverste Loesung:

• GraphQL als API-Gateway: Dein Frontend spricht mit einer GraphQL-Schicht, die intern REST-Microservices orchestriert. Das Frontend bekommt die Flexibilitaet von GraphQL, waehrend die Backend-Services einfache REST-APIs bleiben.
• REST fuer oeffentliche Endpunkte, GraphQL intern: Partner und Drittanbieter nutzen eine dokumentierte REST-API, waehrend interne Teams die Flexibilitaet von GraphQL geniessen.
• REST fuer Datei-Operationen, GraphQL fuer Daten: File Uploads und Downloads laufen ueber REST-Endpunkte, alle anderen Datenanfragen ueber GraphQL.

Schrittweise Migration von REST zu GraphQL

Wenn du bereits eine REST-API hast und GraphQL einfuehren willst, muss das kein Big-Bang sein. Eine bewaehrte Migrationsstrategie:

1. Phase 1 — GraphQL-Wrapper: Setze eine GraphQL-Schicht vor deine bestehende REST-API. Die Resolver rufen intern die REST-Endpunkte auf. Das Frontend kann sofort GraphQL nutzen, ohne dass das Backend umgebaut wird.
2. Phase 2 — Schrittweise Abloesung: Ersetze nach und nach die REST-Calls in den Resolvern durch direkte Datenbankzugriffe. Ein Service nach dem anderen, ohne den laufenden Betrieb zu stoeren.
3. Phase 3 — Optimierung: Implementiere DataLoader, Caching und Query-Complexity-Limits. Optimiere die Resolver fuer deine haeufigsten Query-Patterns.

Sicherheitsaspekte im Vergleich

Beide Technologien haben spezifische Sicherheitsanforderungen:

• REST: Rate Limiting pro Endpunkt, Input-Validierung, CORS-Konfiguration, Authentifizierung via JWT oder OAuth2. Bewaehrte Patterns, gut dokumentiert.
• GraphQL: Zusaetzlich zu den REST-Massnahmen brauchst du Query-Depth-Limiting (verhindert uebermaeßig verschachtelte Queries), Query-Complexity-Analysis (begrenzt die Gesamtkomplexitaet) und eventuell eine Allowlist fuer Queries (Persisted Queries).

GraphQL erfordert mehr Aufwand bei der Absicherung, weil der Client die Queries kontrolliert. Ohne Limits koennte ein Angreifer eine monstroes verschachtelte Query senden, die deinen Server in die Knie zwingt.

Fazit: Es gibt keine falsche Wahl — nur eine unpassende

REST und GraphQL sind keine Konkurrenten — sie sind Werkzeuge fuer unterschiedliche Anforderungen. REST ist erprobt, einfach und punktet bei Caching und oeffentlichen APIs. GraphQL bietet Flexibilitaet, Effizienz und eine hervorragende Developer Experience fuer komplexe, datenintensive Anwendungen.

Die wichtigste Erkenntnis: Die beste API-Technologie ist die, die dein Team produktiv macht und die Anforderungen deiner Nutzer optimal erfuellt. Nicht die, die auf Twitter gerade am meisten Buzz erzeugt.

Wenn du vor einer Architekturentscheidung stehst und unsicher bist, welcher Ansatz fuer dein Projekt der richtige ist, sprich mit uns. Bei WAO designen und bauen wir APIs — sowohl REST als auch GraphQL — und beraten dich ehrlich, welche Technologie fuer deinen konkreten Use Case am besten passt. Schau dir unsere technischen Services an, um mehr ueber unser API-Design und unsere Backend-Expertise zu erfahren.