RESTful API vs. GraphQL: Den richtigen Zugang zu Anwendungsdaten waehlen

Wenn eine Anwendung ein Frontend, eine mobile App, ein Admin-Dashboard und vielleicht Integrationen von Drittanbietern bekommt, wird ihre API nach und nach von einem blossen Verbindungsweg zu einem wichtigen Teil des Systemdesigns. Dann lautet die wiederkehrende Frage nicht mehr: „Wie senden wir JSON?“, sondern: „Reicht eine RESTful API noch aus, oder ist es Zeit fuer GraphQL?“

Ich habe diese Debatte oft wie die Suche nach dem beeindruckendsten Fahrzeug erlebt. Tatsächlich ist eine API eher der Eingang eines Hauses: Die richtige Tuer haengt davon ab, wer kommt, was mitgenommen werden muss und wie oft Menschen ein- und ausgehen. REST und GraphQL koennen beide Daten gut liefern, organisieren diesen Zugang aber unterschiedlich.

Mit dem Problem beginnen, nicht mit dem Trend

Eine RESTful API organisiert Daten ueber Ressourcen. Hat eine Anwendung Benutzer, Artikel und Kommentare, begegnen uns meist Endpunkte wie /api/articles, /api/articles/42 oder /api/articles/42/comments. HTTP-Methoden geben Handlungen Bedeutung: GET liest, POST erstellt, PATCH aktualisiert und DELETE entfernt.

GraphQL verfolgt einen anderen Ansatz. Meist gibt es einen einzigen Endpunkt, und der Client erklaert selbst, welche Datenform er braucht. Der Server stellt ein Schema als Vertrag bereit: welche Daten verfuegbar sind, wie sie zusammenhaengen und welche Operationen erlaubt sind. Statt nur „Artikel Nummer 42“ anzufordern, kann der Client Titel, Autor und die drei neuesten Kommentare in einer Anfrage abrufen.

Dieser Unterschied ist wichtig, weil auch die zu loesenden Probleme verschieden sind. REST ist stark, wenn Ressourcen und Anwendungsablaeufe recht klar sind. GraphQL wird attraktiv, wenn viele Ansichten Daten in unterschiedlichen Zusammenstellungen brauchen. Fuehre GraphQL nicht nur ein, weil es modern klingt; mehr Flexibilitaet bringt immer mehr Verantwortung auf dem Server mit sich.

REST: ein leicht lesbarer Weg

Die Staerke von REST liegt in seiner gedanklichen Einfachheit. Eine URL gibt einen deutlichen Hinweis darauf, worauf zugegriffen wird. Beim Lesen von Nginx-Logs oder beim Testen eines Endpunkts mit curl verstehen wir den Zweck einer Anfrage schnell. HTTP-Caching, Statuscodes, Rate Limits pro Endpunkt und Dokumentation folgen zudem Mustern, die Entwickler und ihre Werkzeuge breit kennen.

Ein Endpunkt fuer eine Artikelliste kann so einfach aussehen:

curl "https://example.com/api/articles?limit=10&page=1" \
  -H "Accept: application/json"

Seine Antwort kann die Artikelliste und Metadaten zur Seitennavigation enthalten. Braucht eine Detailseite Autor und Kategorien, kann das Backend den Parameter include=author,categories anbieten oder eine vereinbarte Detaildarstellung bereitstellen. Dieses Muster ist nicht immer am flexibelsten, aber oft ausreichend und stabil.

Die Nachteile zeigen sich, wenn ein Bildschirm Daten aus vielen Bereichen benoetigt. Eine mobile App muss vielleicht nacheinander Profil-, Neueste-Artikel-, Benachrichtigungs- und Statistik-Endpunkte aufrufen. Fehlen die benoetigten Daten noch in einer Antwort, nennt man das under-fetching. Umgekehrt kann ein zu umfangreicher Endpunkt viele Felder senden, die eine bestimmte Ansicht nie nutzt; das ist over-fetching.

Diese Probleme bedeuten nicht automatisch, dass REST gescheitert ist. Ansichtsbezogene Endpunkte, Parameter zur Feldauswahl, gute Seitennavigation oder ein BFF (Backend for Frontend) loesen sie oft ausreichend. Eine API aufzuraeumen ist meist guenstiger, als das gesamte Kommunikationsmuster zu ersetzen.

GraphQL: Clients fordern nur die benoetigten Daten an

Mit GraphQL kann der Client die Daten beschreiben, die er erhalten moechte. Die folgende Abfrage fordert die Details eines Artikels an, jedoch nur die Felder, die die Seite verwendet:

query ArticleDetail($slug: String!) {
  article(slug: $slug) {
    title
    publishedAt
    author {
      name
    }
    categories {
      name
    }
    comments(limit: 3) {
      name
      body
    }
  }
}

Fuer ein sich schnell entwickelndes Frontend ist das bequem. Ein Designer aendert eine Artikelkarte, der Frontend-Entwickler fuegt ein im Schema verfuegbares Feld hinzu, und das Backend braucht keinen neuen Endpunkt fuer eine einzige Antwortvariante. Ein typisiertes Schema verbessert auch die Werkzeuge: Editoren bieten Autovervollstaendigung, Abfragen werden vor der Verarbeitung validiert, und die API-Dokumentation lebt bei ihrer Definition.

Diese Bequemlichkeit verlangt dennoch Sorgfalt. Eine kompakt wirkende GraphQL-Abfrage kann viele Datenbankabfragen ausloesen, wenn ihre Resolver nachlaessig sind. Das Problem der N+1 query entsteht oft, wenn der Server Artikel abruft und dann den Autor jedes Artikels einzeln laedt. DataLoader, Eager Loading und Grenzen fuer die Abfragekomplexitaet sind kein Beiwerk, sondern wesentliche Teile einer gesunden GraphQL-Implementierung.

Sicherheit und Leistung bleiben unsere Aufgabe

Weder REST noch GraphQL werden allein durch das richtige Format sicher. Authentifizierung klaert, wer die API aufruft; Autorisierung bestimmt, auf welche Daten oder Handlungen diese Person zugreifen darf. Autorisierungspruefungen muessen nah an Ressource oder Resolver liegen und duerfen sich nicht nur auf im Frontend versteckte Schaltflaechen stuetzen.

Bei REST koennen wir Rate Limits nach Endpunkt und Methode setzen. Bei GraphQL erfordert der einzelne Endpunkt mehr Sorgfalt: Begrenze Tiefe und Komplexitaet von Abfragen, setze maximale Limits fuer die Seitennavigation, speichere bei Bedarf freigegebene Abfragen fuer oeffentliche Operationen und beobachte langsame Resolver. Gehe nie davon aus, dass eine Client-Abfrage sinnvoll ist, nur weil ihre Syntax gueltig ist.

Auch Caching hat einen anderen Charakter. REST-Antworten auf GET koennen Browser-Caches, CDNs und HTTP-Header leicht nutzen. GraphQL verwendet haeufig POST-Anfragen und sehr spezifische Antwortformen; daher wird Caching oefter im Client oder in der Serverschicht behandelt. Das ist kein grundsaetzlicher Nachteil, muss aber von Anfang an bedacht werden, besonders bei oeffentlichen Seiten mit hohem Traffic.

Wann waehle ich welches?

Ich entscheide mich meist fuer eine RESTful API bei gewoehnlichem CRUD, oeffentlichen Integrationen, Diensten mit starkem HTTP-Caching oder kleinen bis mittleren Projekten, deren Teams den geradlinigsten Debugging-Weg wollen. REST ist auch angenehm, wenn es wenige API-Konsumenten gibt und deren Datenbedarf relativ stabil ist.

GraphQL ist eher erwaegenswert, wenn ein Backend viele Clients mit unterschiedlichen Datenbeduerfnissen bedient, etwa ein Web-Dashboard, eine Android-App, eine iOS-App und ein internes Panel. Es ist auch nuetzlich, wenn Datenbeziehungen komplex sind und sich die UI schnell aendert. Die Bedingung ist klar: Das Team muss bereit sein, Schema, Resolver, Observability und Abfrageregeln diszipliniert zu pflegen.

Es gibt noch eine oft realistischere Wahl: Zuerst REST einsetzen und GraphQL nur dort ergaenzen, wo echte Probleme beim Datenabruf entstehen. Beide koennen nebeneinander bestehen. Es gibt keinen Preis dafuer, alle Endpunkte auf einmal umzuziehen; eine grosse Migration ohne wirklichen Bedarf ist wie der Umbau einer Kueche, nur um einen Wasserhahn auszutauschen.

Einen langweiligen, aber klaren Vertrag entwerfen

API-Technologien duerfen verschieden sein, doch das Prinzip bleibt: Der Vertrag muss konsistent sein. Verwende verstaendliche Feldnamen, einheitliche Datumsformate, maschinenlesbare Fehler, dokumentierte Seitennavigation und Versionierung, wenn eine Aenderung wirklich Kompatibilitaet bricht. Schreibe Beispiele fuer Anfragen und Antworten und teste aus Sicht des Clients, nicht nur aus Sicht des Backend-Controllers.

Bei einem persoenlichen Projekt oder Homeserver hat Einfachheit grossen Wert. Eine API, die du nach sechs Monaten wieder verstehen kannst, ist wertvoller als eine Architektur, die anspruchsvoll aussieht, aber bei einem Fehler mitten in der Nacht schwer nachzuvollziehen ist. Beginne mit der Datenform, die die Anwendung heute wirklich braucht, miss echte Engpaesse und verbessere sie aus begruendbaren Gruenden.

Fazit

Eine RESTful API ist keine alte Technologie, die sofort aufgegeben werden muss, und GraphQL ist keine automatische Antwort fuer jede Anwendung. REST bietet einen vertrauten, gut cachebaren und leicht zu betreibenden Weg. GraphQL gibt Clients grosse Freiheit, verlangt vom Backend jedoch mehr Disziplin.

Waehle nach der Form des Problems, den Faehigkeiten des Teams und den kurzfristigen Anforderungen, nicht weil eine Technologie gerade populaer ist. Wenn du REST, GraphQL oder beide in einem Projekt kombiniert hast, teile deine Erfahrung in den Kommentaren. Der nuetzlichste Vergleich kommt meist von Systemen, die tatsaechlich gepflegt wurden.