REST oder GraphQL? API-Auswahl für Unternehmens-Webanwendungen

REST oder GraphQL? Vergleich über Caching, Autorisierung, Fehlermodell, N+1 und Abfragekosten, Entscheidungsbaum und Bedingungen, unter denen tRPC sinnvoll ist.
Technische Zusammenfassung
Technologie
REST, GraphQL, OpenAPI, DataLoader, tRPC, RFC 9110, RFC 9457
Thema
Auswahl des API-Stils einer Anwendung
Niveau
Mittel
Voraussetzungen
  • Kenntnisse zu HTTP-Methoden und Statuscodes
  • Grundlegende Erfahrung im API-Design
In diesem Beitrag7 Abschnitte

In einer Unternehmens-Webanwendung wird der API-Stil einmal gewählt, und dann lebt man jahrelang damit. Diese Entscheidung bestimmt Client-Code, Cache-Architektur, Autorisierungsmodell und Überwachung. Auf die Frage „REST oder GraphQL?“ gibt es keine universell richtige Antwort; welche Variante unter welchen Bedingungen weniger Kopfzerbrechen bereitet, ist aber weitgehend vorhersehbar. Im Folgenden vergleichen wir beide Ansätze für interne Geschäftsanwendungen und Headless-Frontends anhand konkreter Kriterien und liefern am Ende einen Entscheidungsbaum.

Der grundlegende Unterschied beider Ansätze

REST ist kein Protokoll, sondern ein auf HTTP aufbauender Architekturstil. Das System wird in Ressourcen (Bestellung, Kunde, Rechnung) gegliedert; jede Ressource hat eine URI, und Vorgänge werden mit HTTP-Methoden ausgedrückt. Die Form der Antwort bestimmt der Server; der Client bestimmt durch die Wahl des Endpunkts, was er erhält. Der Vertrag wird meist mit einem OpenAPI-Dokument definiert.

GraphQL ist dagegen eine Abfragesprache und ein Typsystem. Der Server veröffentlicht das gesamte Datenmodell als ein Schema; der Client schreibt bei jeder Anfrage im Abfragetext, welche Felder er möchte. Für den Transport werden meist ein einziger HTTP-Endpunkt (meist /graphql) und POST genutzt. Das Schema ist der Vertrag selbst und wird per Introspektion von Werkzeugen gelesen.

Am schnellsten sieht man den Unterschied, wenn man denselben Bildschirm in beiden Stilen modelliert. Denken Sie an einen Bestelldetail-Bildschirm: Bestellkopf, Positionen, Name des Kunden und letzter Versandstatus.

# REST: ressourcenorientierte Endpunkte
GET /api/v1/bestellungen/48213
GET /api/v1/bestellungen/48213/positionen
GET /api/v1/kunden/9071
GET /api/v1/bestellungen/48213/sendungen?sortierung=-datum&limit=1

# GraphQL: eine bildschirmorientierte Abfrage
query BestellDetail($id: ID!) {
  bestellung(id: $id) {
    nr
    datum
    kunde { firma }
    positionen { artikelNr menge einzelpreis }
    letzteSendung { status sendungsNr }
  }
}

Vier Anfragen auf REST-Seite sind für sich kein Problem; mit HTTP/2 und HTTP/3 sind parallele Anfragen günstig. Die eigentliche Frage ist eine andere. Wer übernimmt das Zusammenführen: der Client, ein zweckgebundener Endpunkt auf dem Server oder eine GraphQL-Resolver-Schicht?

Client-Anforderungen und Datenabruf

GraphQL glänzt, wenn es viele Clients gibt, die Daten in unterschiedlicher Form anfordern. Wollen Webpanel, mobile App und Händlerportal unterschiedliche Teilmengen derselben Bestelldaten, schreibt jeder Client seine eigene Abfrage, statt für jeden einen eigenen Endpunkt zu schreiben oder mehr Daten als nötig zurückzugeben (Over-Fetching). Neue Felder im Schema brechen bestehende Clients nicht; zu entfernende Felder werden mit @deprecated markiert.

REST ist dagegen bequem in internen Anwendungen, in denen die Zahl der Clients gering und der Datenbedarf stabil ist und sich die Ressourcen natürlich auf CRUD abbilden. Einem Anfragemanagementsystem mit nur einem Web-Frontend ein GraphQL-Schema, Resolver und eine Client-Cache-Bibliothek hinzuzufügen, bringt mehr bewegliche Teile als das Problem, das es löst. Dieses Bild sehen wir in der Praxis häufig: eine GraphQL-Schicht für eine Anwendung mit drei Bildschirmen, deren Wartung niemand übernimmt. Für wenige Bildschirme genügen meist einige aggregierende Endpunkte (/bestellungen/48213?include=positionen,kunde oder ein zweckgebundener BFF-Endpunkt).

Im Headless-CMS-Szenario entscheidet meist das CMS: Manche Produkte bieten nur REST, manche REST und GraphQL. Die Auswahl der Inhaltsschicht beschreiben wir im Beitrag Was ist ein Headless CMS und wann ist es die richtige Wahl; hier geht es um die eigene Geschäfts-API der Anwendung.

Caching und HTTP-Semantik

Der am meisten unterschätzte Vorteil von REST ist, dass es den Cache-Mechanismus von HTTP unverändert nutzt. Da GET-Anfragen über die URI identifiziert werden, speichern Browser, Reverse-Proxy und CDN-Schichten Antworten gemäß dem Header Cache-Control; bei einer bedingten Anfrage mit ETag und If-None-Match wird für unveränderte Daten ein 304 Not Modified ohne Body zurückgegeben. Diese Verhaltensweisen sind in RFC 9110 (HTTP Semantics) und RFC 9111 (HTTP Caching) definiert. Eine zusätzliche Bibliothek ist nicht nötig.

Da GraphQL-Anfragen meist als POST an dieselbe URI gehen, fallen Zwischenschicht-Caches weg. Caching wandert an zwei Stellen:

  • Clientseitiger normalisierter Cache: Bibliotheken wie Apollo Client oder urql zerlegen Antworten nach Typ und ID-Feld und speichern sie. Das ist leistungsfähig; Fehler durch inkonsistente Caches zu debuggen, ist aber deutlich schwieriger als bei REST.
  • Persistierte Abfragen (Persisted Queries): Statt des Abfragetexts wird ein Hashwert gesendet; Abfragen können per GET erfolgen und im CDN gecacht werden. Derselbe Mechanismus dient auch als Sicherheitskontrolle, die nur vorab genehmigte Abfragen ausführen lässt.

In internen Unternehmensanwendungen sind Daten meist benutzerspezifisch und gelangen ohnehin nicht in einen gemeinsamen Cache. Dort schrumpft der Vorteil des HTTP-Caches. Bei APIs, die öffentliche Daten wie Produktkatalog, Preisliste oder Inhalte bereitstellen, bietet REST dagegen eine erhebliche operative Erleichterung. Details zu den Headern im Leitfaden Cache-Control-Header.

Autorisierung und Fehlermodell

Bei REST wird Autorisierung natürlich auf Endpunkt- und Ressourcenebene aufgebaut: Die Frage „Darf dieser Benutzer diese Bestellung lesen?“ wird an einer Stelle beantwortet. Da bei GraphQL eine einzige Abfrage viele Typen und Felder berührt, verlagert sich die Prüfung auf Feld- und Objektebene. Ein Vertriebsmitarbeiter darf das Feld Kunde.firma sehen, das Feld Kunde.kreditlimit nicht. Verteilt sich diese Prüfung auf Resolver, leakt ein einziges vergessenes Feld Daten. Das richtige Muster: Berechtigungsregeln nicht in Resolvern, sondern zentral in der Geschäfts-/Serviceschicht anwenden, die die Resolver aufrufen. So gilt dieselbe Regel für REST- und GraphQL-Einstiegspunkte gleichermaßen. Für das Design rollen- und mandantenbasierter Berechtigungen siehe den Beitrag Autorisierungsarchitektur im B2B-Portal.

Auch das Fehlermodell funktioniert unterschiedlich:

Thema REST GraphQL
Fehlersignal HTTP-Statuscode (400, 403, 404, 409, 422…) errors-Array in der Antwort
Teilerfolg Meist nicht; die Anfrage ist entweder erfolgreich oder fehlerhaft Ja; Daten und Fehler können gemeinsam zurückkommen
Standardisierter Fehler-Body RFC 9457 Problem Details (application/problem+json) message, path, extensions.code
Monitoring Metriken nach Statuscode einfach Inhalt von errors muss separat erfasst werden

In GraphQL vereinfacht es den Client-Code, Geschäftsregelfehler (Bestand unzureichend, Freigabelimit überschritten) nicht in das errors-Array zu werfen, sondern im Schema als Ergebnistyp zu modellieren; etwa indem eine Mutation den Union-Typ BestellungAngelegt | BestandUnzureichend zurückgibt. Bei REST wird dieselbe Situation mit 409 oder 422 und einem maschinenlesbaren Feld type im Problem-Details-Body ausgedrückt. Die Falle auf Überwachungsseite ist offensichtlich: Ein Alarm, der bei GraphQL nur den HTTP-Statuscode betrachtet, sieht den Fehler nie.

Performance: N+1 und Abfragekosten

Die bekannteste Performancefalle von GraphQL ist N+1. Wird eine Liste mit 50 Bestellungen angefordert und läuft der Resolver, der das Feld kunde jeder Bestellung auflöst, einzeln, gehen 1 Listenabfrage und 50 Kundenabfragen an die Datenbank. Ein Teil der als Datenbanklangsamkeit gemeldeten Tickets ist in Wirklichkeit genau das. Die Standardlösung ist das DataLoader-Muster, das Einzelladevorgänge innerhalb derselben Anfrage sammelt und in eine einzige Sammelabfrage umwandelt:

// Pro Anfrage erzeugt; nicht zwischen Anfragen geteilt
const kundenLoader = new DataLoader(async (ids: readonly string[]) => {
  const datensaetze = await db.kunde.findMany({ where: { id: { in: [...ids] } } });
  const karte = new Map(datensaetze.map((k) => [k.id, k]));
  return ids.map((id) => karte.get(id) ?? null);
});

const resolvers = {
  Bestellung: {
    kunde: (bestellung, _args, ctx) => ctx.kundenLoader.load(bestellung.kundeId),
  },
};

Der Loader muss pro Anfrage erzeugt werden. Wird anwendungsweit ein einziger Loader genutzt, kann ein von einem Benutzer geladener Datensatz aus dem Cache in die Anfrage eines anderen, nicht berechtigten Benutzers gelangen.

Das zweite Risiko ist, dass der Client die Abfragekosten bestimmen kann. Tief verschachtelte Abfragen (bestellung → kunde → bestellungen → positionen → artikel → …) belasten den Server mit einer einzigen Anfrage. In der Produktion sollten drei Grenzen aktiv sein: Limit für die Abfragetiefe, feldbasierte Kosten-/Komplexitätsberechnung und Obergrenze für Paginierungsargumente. Nutzt nur Ihr eigenes Frontend die API, ist eine Allowlist persistierter Abfragen die stärkste Kontrolle. Bei REST ist das Risiko begrenzter, da die Kosten jedes Endpunkts im Design festgelegt werden. Mit zunehmenden flexiblen Erweiterungsparametern wie ?include= sind dort aber dieselben Grenzen nötig.

Entscheidungsbaum und Vergleichstabelle

Beantworten Sie diese Fragen der Reihe nach; in den meisten Projekten klärt sich die Wahl von selbst:

  1. Wird die API nach außen geöffnet (Geschäftspartner, Kundensystem, Client in anderer Sprache)? Wenn ja, beginnen Sie mit REST + OpenAPI; Werkzeugunterstützung und HTTP-Gewohnheiten der Konsumenten sind hier am breitesten. Die Weiterentwicklung einer veröffentlichten API beschreibt der Beitrag Strategien zur REST-API-Versionierung.
  2. Konsumieren mehrere Frontends dieselben Daten in unterschiedlicher Form? Wenn ja und das Datenmodell relational reichhaltig ist, ist GraphQL ein starker Kandidat.
  3. Liegen Frontend und Backend im selben TypeScript-Repository, und bedient die API nur diese Anwendung? Wenn ja, erledigen typgeteilte RPC-Ansätze wie tRPC oder Server Actions die Arbeit ohne zusätzliche Schemaschicht.
  4. Werden öffentliche, cachebare Daten bereitgestellt? Wenn ja, ist die HTTP-Cache-Kompatibilität von REST entscheidend.
  5. Hat das Team Erfahrung mit GraphQL-Schemadesign, DataLoader und Kontrolle der Abfragekosten? Wenn nicht, planen Sie die Zeit zum Aufbau dieser Kompetenz ein oder beginnen Sie mit REST.
Kriterium REST GraphQL tRPC
Vertrag OpenAPI GraphQL-Schema TypeScript-Typen
HTTP-Cache Nativ Eingeschränkt mit persistierten Abfragen Eingeschränkt
Flexible Datenauswahl Abhängig vom Endpunktdesign Stark Abhängig vom Prozedurdesign
Granularität der Berechtigung Ressourcenebene Feldebene erforderlich Prozedurebene
Externe Konsumenten Sehr gut geeignet Geeignet Nicht geeignet
Zusätzlicher operativer Aufwand Niedrig Mittel–hoch Niedrig

Auch eine gemischte Architektur ist ein legitimes Ergebnis: REST für Partnerintegrationen und Dateivorgänge, eine GraphQL-BFF-Schicht für komplexe Bildschirme und eine gemeinsame Serviceschicht, in der Geschäftsregeln zentral gebündelt sind. Welcher Stil auch gewählt wird, erzeugen Sie die API-Typen automatisch für den Client; manuell synchron gehaltene Typen driften früher oder später auseinander. Wie das aufgebaut wird, beschreiben wir im Beitrag Standards für TypeScript-Codebasen. Beim Entwurf einer zu Ihren Prozessen passenden API-Schicht können Sie Unterstützung über unsere Leistungen Entwicklung individueller Webanwendungen oder API-First- und Headless-Architektur erhalten. Primärquellen für die Spezifikationen sind die Lernressourcen von graphql.org und RFC 9457.

Häufig gestellte Fragen

Brauchen wir mit GraphQL überhaupt keine REST-API mehr?

Meistens doch. Datei-Upload und -Download, Webhook-Empfänger, Health-Check-Endpunkte und Integrationen für externe Geschäftspartner lassen sich mit REST-Endpunkten, die HTTP-Semantik direkt nutzen, schlanker lösen. In vielen Unternehmenssystemen laufen GraphQL für das Frontend und REST für Integrationen und Dateivorgänge nebeneinander.

Ist es normal, dass GraphQL-Antworten trotz Fehler HTTP 200 liefern?

Ja. Da eine GraphQL-Antwort sowohl Teildaten als auch ein errors-Array enthalten kann, liefern viele Server bei Fehlern auf Feldebene 200. Überwachungs- und Alarmsysteme sollten daher nicht nur den HTTP-Statuscode betrachten, sondern auch das errors-Array und die Fehler-Erweiterungscodes als Metrik erfassen. Kann eine Anfrage gar nicht ausgeführt werden (Syntax- oder Validierungsfehler), ist eine 4xx-Antwort der Ansatz, den der Entwurf der Spezifikation GraphQL over HTTP empfiehlt.

Wann ist tRPC eine sinnvolle Wahl?

Werden Frontend und Backend im selben TypeScript-Repository entwickelt, konsumiert nur diese Anwendung die API und ist keine Öffnung nach außen geplant, bietet tRPC Typsicherheit vom Client bis zum Server, ohne ein Schema zu schreiben. Gibt es Clients in anderen Sprachen, Partnerintegrationen oder langfristigen Versionierungsbedarf, sind REST oder GraphQL besser geeignet.

Ist es richtig, vor eine bestehende REST-API eine GraphQL-Schicht zu setzen?

Muss das Frontend viele REST-Aufrufe zusammenführen, kann eine GraphQL-Schicht als BFF (Backend for Frontend) nützlich sein. Diese Schicht bringt aber das Risiko von N+1-Aufrufen in Resolvern, doppelter Berechtigungsprüfung an zwei Stellen und zusätzlicher Latenz. Prüfen Sie zuerst, ob sich der Bedarf mit einigen zweckgebundenen REST-Endpunkten lösen lässt.

Support

Kontaktieren Sie uns für Support oder eine Bestandsaufnahme zu diesem Thema.

Kontaktformular
[email protected]

Eretek Web

Wir bauen Unternehmenswebsites, WordPress- und CMS-Plattformen, Intranet- und SharePoint-Portale, Dokumentenmanagement sowie Formular- und Freigabeprozesse auf und halten sie sicher und aktuell.

Wissenszentrum

Weitere Beiträge