Drupal als Backend: GraphQL, JSON:API, RESTful und der teure Fehler, der sich in der API-Wahl versteckt

Ein CTO fragte mich einmal mitten in einem Planungsmeeting für ein entkoppeltes Drupal-Projekt: „Welche API sollten wir also verwenden?“

Für einen Moment wurde es still im Raum. Das Frontend wollte GraphQL. Das Backend wollte JSON:API. Ein Integrationsanbieter war bereits von REST ausgegangen. Der Product Owner wollte einfach nur, dass die mobile App nicht mehr auf Website-Releases warten muss.

Diese kleine Frage klingt meistens technisch. Das ist sie nicht. Sie ist eine Governance-Frage, eine Budgetfrage und manchmal eine Einstellungsfrage im Entwickler-Hoodie.

Drupal kann ein sehr leistungsfähiges Backend für entkoppelte Produkte sein. Es verfügt bereits über strukturierte Inhalte, Rollen, Berechtigungen, Workflows, Revisionen, Übersetzungen, Medienverwaltung, Taxonomie und ein ausgereiftes Modul-Ökosystem. Der unangenehme Teil besteht darin zu entscheiden, wie diese Inhalte Drupal verlassen. Der Drupal-Core bietet native Unterstützung für JSON:API, GraphQL ist über ein beigesteuertes Modul verfügbar, und das RESTful-Web-Services-Modul von Drupal bleibt eine Option für benutzerdefinierte ressourcenartige Endpoints. Drupals eigene Dokumentation zu entkoppelten Architekturen formuliert die Aufteilung klar: JSON:API ist im Core, GraphQL ist beigesteuert, und Drupal kann Inhalte über APIs an ein externes Frontend ausliefern.

Und trotzdem treffen Teams weiterhin schlechte Entscheidungen.

Sie wählen GraphQL, weil es modern klingt. Sie wählen REST, weil es jeder schon einmal benutzt hat. Sie wählen JSON:API, weil es vorhanden ist. Nichts davon ist eine Strategie.

Hier ist die schärfere Version: Für die meisten Drupal-basierten Content-Plattformen sollte JSON:API der Standardausgangspunkt sein. GraphQL sollte man sich verdienen müssen. REST sollte für Fälle reserviert bleiben, in denen die anderen beiden Optionen zu breit oder zu meinungsstark sind.

Das wird einige Leute ärgern. Gut so.

Beginnen Sie mit dem langweiligen Gewinner: JSON:API

JSON:API ist auf die bestmögliche Weise langweilig.

Das JSON:API-Modul im Drupal-Core implementiert die JSON:API-Spezifikation für Drupal-Entitäten. Es bietet eine konfigurationsfreie, meinungsstarke Möglichkeit, CRUD-Operationen für Website-Inhalte bereitzustellen, und ist mit Drupals Entity API, Field API, Caching-, Authentifizierungs- und Autorisierungssystemen verknüpft.

Dieser Satz enthält den Teil, der Führungskräfte interessieren sollte: Core-Modul.

Core ist wichtig. Core bedeutet in der Regel weniger Überraschungen durch Anbieter, einfachere Wartungsplanung, eine klarere Sicherheitslage und ein geringeres Risiko nach dem Muster „wir brauchen genau den einen Auftragnehmer, der die benutzerdefinierte API-Schicht versteht“. Die JSON:API-Dokumentation von Drupal sagt, dass das Modul APIs rund um Entitätstypen und Bundles bereitstellt und Filterung, Includes, Paginierung, Sortierung, Revisionen, Übersetzungen, GET, POST, PATCH, DELETE, Datei-Uploads und Ressourcenanpassung über Events unterstützt.

Ein praktisches Beispiel: Stellen Sie sich ein Medienunternehmen mit Artikeln, Autoren, Themen, Teasern für Landingpages und Bildern vor. Das Frontend-Team benötigt Artikelseiten in Next.js. Die mobile App benötigt denselben Artikeltext, das Hero-Bild, den Autorennamen und verwandte Themen. JSON:API kann diese Drupal-Entitäten bereitstellen, ohne dass das Backend-Team eine API-Sprache von Grund auf neu erfinden muss. Verwandte Ressourcen können über Includes eingebettet werden, und Sammlungen können gefiltert oder paginiert werden.

Ist der Payload hübsch? Manchmal. Manchmal sieht er aus, als hätte ein Ausschuss ihn nach einem langen Mittagessen entworfen.

Aber genau darum geht es auch. JSON:API ist eine Spezifikation, nicht der persönliche Geschmack eines Entwicklers. Die offizielle JSON:API-Website beschreibt es als Spezifikation zum Erstellen von APIs in JSON, mit gemeinsamen Konventionen, die Diskussionen über die Form von Antworten reduzieren und Teams helfen, allgemeine Werkzeuge zu verwenden. Sein Medientyp ist application/vnd.api+json, und Version 1.1 wurde am 30. September 2022 finalisiert.

Darin steckt ein versteckter Managementvorteil. Ein standardisiertes Antwortformat bedeutet, dass Onboarding weniger tribal ist. Ein neuer Frontend-Entwickler mag immer noch über die verschachtelte Struktur aus data, attributes und relationships fluchen. In Ordnung. Wenigstens flucht er über etwas Dokumentiertes.

Der Haken, den niemand erwähnen möchte

JSON:API legt Drupals Content-Modell ziemlich direkt offen. Das kann eine Stärke sein, besonders wenn Drupal die redaktionelle Quelle der Wahrheit ist. Es kann aber auch zu viel von Drupals interner Struktur ins Frontend durchsickern lassen.

Wenn Ihr Content-Modell sauber ist, wirkt JSON:API effizient. Wenn Ihr Content-Modell ein Museum alter Kompromisse ist, macht JSON:API das Chaos sichtbar.

Ich habe „Article“-Content-Types mit Feldern wie field_new_body_2021, field_mobile_summary, field_legacy_related und field_do_not_use gesehen. JSON:API verwandelt das nicht auf magische Weise in eine elegante Produkt-API. Es legt das Modell offen, das Sie tatsächlich haben. Vielleicht ein wenig grausam. Aber nützlich.

Die Drupal-Dokumentation zieht außerdem eine klare Grenze: JSON:API übernimmt entitätsorientiertes CRUD, aber Geschäftsregeln wie Login, Passwortzurücksetzung und Kontoerstellung liegen außerhalb der Aufgabe von JSON:API. Wenn Ihre Anwendung Domänenaktionen wie „Anbieter genehmigen“, „Verlängerungsangebot berechnen“ oder „Schadensfall einreichen“ benötigt, zwängen Sie diese nicht in Content-Entity-Endpoints, nur weil das Modul bequem ist.

Dieser Weg wird schnell hässlich.

GraphQL wirkt elegant, weil es den Schmerz verlagert

GraphQL ist verführerisch. Das Frontend fragt genau die Felder ab, die es möchte. Die Antwort hat dieselbe Form wie die Abfrage. Es besitzt ein typisiertes Schema. Es fühlt sich für komponentenbasierte Frontends gemacht an, weil es das, ehrlich gesagt, auch war. Die offizielle GraphQL-Website beschreibt GraphQL als Open-Source-Abfragesprache und serverseitige Laufzeitumgebung für APIs mit einem stark typisierten Schema und zeigt, wie der Client ausgewählte Felder anfordert, statt eine feste Serverantwort zu erhalten.

Für Frontend-Teams ist das eine echte Verbesserung.

Nehmen wir eine Homepage aus Komponenten: Hero, hervorgehobene Artikel, Events, Sponsorenplätze, Navigation, regionale Hinweise. Mit REST ruft das Frontend möglicherweise mehrere Endpoints auf. Mit JSON:API kann es eine Sammlung anfordern und verwandte Ressourcen einschließen, aber die Struktur folgt weiterhin Entitätsbeziehungen. Mit GraphQL kann die Abfrage näher am Bildschirm liegen. Das ist wichtig, wenn Teams Produktoberflächen schnell ausliefern.

Das GraphQL-Modul von Drupal ermöglicht Entwicklern, ein GraphQL-Schema für Drupal 10 und 11 zu erstellen und bereitzustellen. Es basiert auf webonyx/graphql-php, unterstützt die offizielle GraphQL-Spezifikation, enthält GraphiQL unter /graphql/explorer und bietet Entwicklern Data-Producer-Plugins sowie benutzerdefinierten Code für Schema-Arbeiten.

Lesen Sie die Formulierung genau: „erstellen und bereitstellen“.

Das aktuelle Drupal-GraphQL-Modul ist kein magischer Spiegel, der einfach jedes Drupal-Feld in einer sauberen API reflektiert. Drupal.org sagt, dass die ältere Version 3.x automatisch ein Schema aus Drupal-Entitäten generierte und Drupal-Details über die API offenlegte, während 4.x das Schema-Design dem Entwickler überlässt, damit Drupal-Interna verborgen werden können. Dieselbe Seite sagt, dass 4.x vom Entwickler verlangt, das Schema einzurichten und zu mappen.

Das ist keine Fußnote. Das ist die Rechnung.

GraphQL kann Ihnen einen sauberen Vertrag zwischen Produkt und Content-Speicher geben. Aber jemand muss diesen Vertrag entwerfen. Jemand muss ihn pflegen, wenn Redakteure Felder hinzufügen, wenn sich das Designsystem ändert, wenn Personalisierung hinzukommt, wenn die Rechtsabteilung regionale Consent-Logik verlangt, wenn das Mobile-Team Offline-Synchronisierung benötigt.

Eigentlich ist das zu höflich formuliert. Jemand muss dafür verantwortlich sein. Ownership ist die fehlende Position in vielen GraphQL-Vorschlägen.

Wann GraphQL die Kosten wert ist

GraphQL ergibt Sinn, wenn die API ein eigenständiges Produkt ist.

Eine große Universität mit Dutzenden von Microsites, einer mobilen App für Studierende, Digital Signage, Fakultätsprofilen, Kurskatalogen und einem Designsystem kann von einer GraphQL-Schicht profitieren. Die Konsumenten sind vielfältig. Der Content-Graph ist tief. Die Frontend-Teams benötigen selektiven Zugriff. Die Organisation möchte vielleicht einen API-Vertrag, der die Eigenheiten von Drupal-Bundles verbirgt.

GraphQL passt auch, wenn Drupal nur eine Quelle unter mehreren ist. Vielleicht kommen Inhalte aus Drupal, Preise aus einem ERP, Verfügbarkeit aus einer Buchungsmaschine und Benutzerberechtigungen aus einem CRM. GraphQL kann Clients ein kohärentes Schema präsentieren, während Resolver Daten aus verschiedenen Systemen abrufen. Das GraphQL-Modell wurde rund um ein stark typisiertes Schema und eine vom Client bestimmte Antwortform entwickelt, und genau deshalb funktioniert es gut in einer solchen Kompositionsschicht.

Aber für eine normale Marketing-Website mit einem Headless-Frontend? Ich wäre skeptisch. Vielleicht sogar leicht genervt.

Wenn der eigentliche Bedarf lautet: „React soll Artikel aus Drupal lesen“, kann GraphQL eine Kostümparty sein. Sie geben Architektur-Budget aus, um nicht JSON:API-Includes und -Filter lernen zu müssen. Schlimmer noch: Sie schaffen möglicherweise eine maßgeschneiderte API-Schicht, die nur zwei Entwickler verstehen.

Die Projektseite von Drupal GraphQL berichtet, dass stabile Releases von Drupals Security-Advisory-Policy abgedeckt sind, und listet aktuelle Releases für Drupal 10 und 11 auf, darunter 8.x-4.14 vom 29. April 2026 sowie eine 5.0.0-Beta für Drupal 10.4 und 11. Das ist gesund. Es entfernt nicht die Designarbeit.

Ein beigesteuertes Modul kann ausgereift sein und trotzdem der falsche Standard sein.

RESTful Web Services: alt, nützlich und meistens überstrapaziert

REST ist zu einem dieser Wörter geworden, die bedeuten, was auch immer der Sprecher gerade braucht. Manchmal bedeutet es sauberes ressourcenorientiertes HTTP. Manchmal bedeutet es: „Wir geben JSON aus einem Controller zurück.“ Manchmal bedeutet es: „Der Anbieter hat uns einen Endpoint und ein PDF gegeben.“

Roy Fieldings Dissertation führte REST als Architekturstil für verteilte Hypermedia-Systeme ein, mit Constraints wie Client-Server-Trennung, zustandsloser Kommunikation, Cache, einer einheitlichen Schnittstelle, geschichteten Systemen und optionalem Code-on-Demand. Diese ursprüngliche Idee ist strenger als vieles, was in Projektplänen REST genannt wird.

Drupals RESTful-Web-Services-Modul ist nützlich, weil es Ressourcen mit bestimmten Methoden, Serialisierungsformaten und Authentifizierung bereitstellen kann. Drupal-Lernmaterial beschreibt REST-Ressourcen für Entitäten, Unterstützung für Methoden wie GET, POST, PATCH und DELETE, JSON- oder XML-Serialisierung sowie Authentifizierung über Basic Auth, Cookies oder andere Module wie OAuth. Es weist außerdem darauf hin, dass unsichere Methoden einen X-CSRF-Token-Request-Header benötigen.

Das macht REST gut für eng begrenzte Integrationsarbeit.

Ein Zahlungsanbieter sendet den Transaktionsstatus an Drupal. Ein Lagersystem ruft eine Liste aktualisierter Produkthandbücher ab. Ein Partnerportal benötigt einen sorgfältig geformten Endpoint für freigegebene Assets. Eine Legacy-Mobile-App erwartet bereits /api/v1/articles/{id} und kann in diesem Quartal nicht neu geschrieben werden.

REST gibt Ihnen Kontrolle. Es gibt Ihnen auch das Syndrom der leeren Seite.

Anders als bei JSON:API, wo die Konventionen bereits gewählt sind, benötigt ein benutzerdefinierter REST-Endpoint Entscheidungen: URL-Struktur, Antwortformat, Fehlerformat, Paginierungsstil, Filtersyntax, Versionierung, Authentifizierung, Cache-Header, Dokumentation, Deprecation-Policy. OpenAPI kann helfen, diese Oberfläche zu dokumentieren, und die OpenAPI Specification ist ein standardisierter, sprachunabhängiger Weg, HTTP-APIs zu beschreiben, sodass Menschen und Computer sie verstehen können, ohne Quellcode zu lesen.

Trotzdem müssen Sie die Entscheidungen treffen.

Und diese Entscheidungen bleiben. Ein schlampig entworfener Endpoint aus Woche zwei kann ein Produkt jahrelang verfolgen, weil irgendeine App-Version im Feld immer noch davon abhängt.

Die Entscheidung lautet nicht: „Welche API ist die beste?“

Diese Fragestellung ist bequem. Entschuldigung, aber das ist sie.

Die bessere Frage lautet: Welche Art von Kopplung kann sich Ihre Organisation leisten?

JSON:API koppelt Konsumenten an Drupals Entitätsmodell. Das ist oft akzeptabel, wenn Drupal das zentrale Content-System ist und das Frontend eine ersetzende Präsentationsschicht darstellt. Der Lohn ist Geschwindigkeit und weniger Backend-Erfindung.

GraphQL koppelt Konsumenten an ein Schema, das Ihr Team entworfen hat. Gut umgesetzt, verbirgt dieses Schema Drupal und drückt die Produktdomäne aus. Schlecht umgesetzt, wird es zu einem zweiten CMS-Modell, das im Code gepflegt wird.

REST koppelt Konsumenten an benutzerdefinierte Endpoints. Das ist hervorragend für spezifische Integrationen und gefährlich für breite Content-Auslieferung, weil jeder Endpoint zu einem Miniaturprodukt mit eigenem Wartungsschwanz wird.

Hier ist die Version, die ich einer Executive Steering Group vorlegen würde.

Tabellen sind ein wenig steril, aber diese spart Meetings.

Worauf Projektmanager achten sollten

Die API-Wahl verändert den Projektplan stärker, als viele zugeben.

Bei JSON:API ist der kritische Pfad das Content-Modelling. Wenn das Content-Modell durchdacht ist, kann die API-Arbeit schnell vorankommen. Wenn das Content-Modell chaotisch ist, verlangsamt sich die Frontend-Entwicklung, weil jede Abfrage einen weiteren redaktionellen Kompromiss offenlegt. Richten Sie Senior-Aufmerksamkeit auf Feldbenennung, wiederverwendbare Paragraph-Patterns, Medienbeziehungen, Taxonomie und Berechtigungen, bevor das Frontend-Team beginnt, Seiten zu verdrahten.

Bei GraphQL ist der kritische Pfad die Schema-Ownership. Wer entwirft das Schema? Wer prüft Breaking Changes? Wer schreibt Resolver? Wer behandelt Performance-Probleme wie verschachtelte Abfragen, die zu viele Backend-Ladevorgänge auslösen? Das Drupal-GraphQL-Modul liefert Werkzeuge und Erweiterungspunkte, einschließlich Data-Producer-Plugins und GraphiQL, aber es ersetzt nicht die Notwendigkeit backendseitiger Engineering-Disziplin.

Bei REST ist der kritische Pfad Vertragsdisziplin. Jeder Endpoint benötigt Dokumentation, Tests, Authentifizierungsregeln, Fehlersemantik und eine Versionierungsstrategie. REST wirkt billig, wenn der erste Endpoint gebaut ist. Der fünfte Endpoint sagt die Wahrheit.

Noch etwas. Authentifizierung wird oft unterschätzt. Drupal JSON:API ist mit Drupals Authentifizierungs- und Autorisierungssystemen verknüpft, und REST kann Authentifizierungsanbieter wie Basic Auth und Cookies verwenden, wobei OAuth häufig über beigesteuerte Module ergänzt wird. Die Lupus-Decoupled-Drupal-Dokumentation verweist auf Simple OAuth als Möglichkeit, API-Anfragen in entkoppelten Setups per Token zu authentifizieren.

Lassen Sie das nicht bis zum Sprint vor dem Launch liegen. Dieser Sprint ist ohnehin schon verflucht.

Performance: das Argument, das alle vereinfachen

GraphQL-Fans sagen, es vermeide Over-Fetching. Stimmt. JSON:API-Fans sagen, Includes reduzieren Round Trips. Auch richtig. REST-Fans sagen, HTTP-Caching sei unkompliziert. Wieder richtig.

Jetzt der unangenehme Teil: Alle drei können schnell sein, und alle drei können langsam sein.

GraphQL kann die Payload-Größe reduzieren, aber komplexe verschachtelte Abfragen können das Backend bestrafen, wenn Resolver nachlässig sind. JSON:API kann Drupals Response-Caching und Includes nutzen, aber Payloads können wortreich sein. REST kann sauber auf HTTP-Caching abgebildet werden, aber benutzerdefinierte Endpoints vergessen Cacheability oft, bis Performance-Tests beginnen. Fieldings REST-Constraints enthalten Cache, weil Cache Netzwerkverkehr und Latenz reduzieren kann, aber veraltete Daten und Cache-Invalidierung bleiben reale Kompromisse. Drupals JSON:API-Dokumentation verknüpft das Modul ausdrücklich mit Drupal Response Caching, während das GraphQL-Modul auf Drupal.org unter Decoupled, Developer tools und Performance kategorisiert ist.

Also nein, GraphQL ist nicht automatisch die „Performance-Option“.

Der erste Performance-Gewinn ist normalerweise ein besseres Content-Modell. Der zweite ist eine Cache-Strategie. Der dritte ist das Vermeiden albernen Client-Verhaltens, etwa denselben Endpoint zwölfmal aufzurufen, weil niemand eine Data-Access-Schicht geschrieben hat.

Glamourös? Nein. Effektiv? Ja.

Ein direkter Auswahlrahmen

Wenn ich einen Gründer oder CTO beraten würde, würde ich mit dieser Reihenfolge beginnen.

Erstens: Verwenden Sie Drupals normale gerenderte Seiten, es sei denn, Sie haben einen Grund zur Entkopplung. Entkopplung bringt zusätzliche Komplexität bei Hosting, Preview, Routing, Cache, Deployment, Authentifizierung und Debugging. Drupals eigene Decoupled-Dokumentation trennt Standard-Drupal von entkoppeltem Drupal, indem sie darauf hinweist, dass das Layout ins Frontend wandert und das Backend Inhalte über APIs bereitstellt. Dieser Wechsel ist nicht kostenlos.

Zweitens: Wenn Sie hauptsächlich wegen eines modernen Frontends entkoppeln, beginnen Sie mit JSON:API. Bauen Sie eine echte Seite, keine Demo. Berücksichtigen Sie Medien, Menüs oder Navigation, verwandte Inhalte, Preview-Anforderungen, Authentifizierung falls nötig und Cache-Verhalten. Sie lernen mehr aus einer hässlichen echten Seite als aus sechs Architekturdiagrammen.

Drittens: Wechseln Sie erst dann zu GraphQL, wenn die Consumer Experience die Schema-Arbeit rechtfertigt. Gute Gründe sind mehrere Frontend-Konsumenten, der Bedarf, Drupal-Interna zu verbergen, komplexe Content-Graphs oder Aggregation über Systeme hinweg. Schlechte Gründe sind „unser Frontend-Entwickler mag Apollo“ und „im Investor-Deck steht GraphQL“.

Viertens: Verwenden Sie REST für Integrationen, die enge Grenzen benötigen. Ein benutzerdefinierter Endpoint für einen Partnerexport kann sauber sein. Eine ganze Content-Plattform aus handgebauten Endpoints kann zu einer Schublade voller unbeschrifteter Schlüssel werden.

Und räumen Sie das Drupal-Modell auf. Bitte. Keine API-Schicht kann ein Content-Modell vollständig retten, für das niemand Verantwortung trägt.

Die Politik von „future-proof“

Führungskräfte mögen den Ausdruck „future-proof“. Ich verstehe, warum. Niemand möchte einen Backend-Neubau genehmigen und achtzehn Monate später hören, dass die gewählte API das Unternehmen in eine Ecke gedrängt hat.

Aber Zukunftssicherheit hat meist weniger damit zu tun, die schickste API auszuwählen, und mehr damit, zu entscheiden, wo Veränderung stattfinden darf.

JSON:API sagt: „Drupals Modell ist der Vertrag.“ Das ist ehrlich und schnell.

GraphQL sagt: „Unser Produktschema ist der Vertrag.“ Das ist mächtig und teuer.

REST sagt: „Dieser Endpoint ist der Vertrag.“ Das ist präzise und lässt sich leicht zu einem Wartungsproblem vervielfachen.

Es gibt keinen universellen Gewinner. Es gibt nur Passung.

Meine Voreingenommenheit ist einfach: Beginnen Sie mit der am wenigsten benutzerdefinierten Lösung, die das Produkt tragen kann. In Drupal bedeutet das normalerweise JSON:API. Fügen Sie GraphQL hinzu, wenn Sie den Owner und das Budget benennen können. Fügen Sie REST hinzu, wenn die Integration spezifisch genug ist, um eine eigene Tür zu verdienen.

Die schlechteste Wahl ist die, die aus Modegründen getroffen wird, denn Mode erscheint nie zur Wartung.

Suchen Sie das führende Drupal-Entwicklungsunternehmen auf dem Markt? Sie haben es gerade gefunden.

Wir sind die beste auf Drupal spezialisierte Digitalagentur, geschaffen, um schnelle, sichere und skalierbare Plattformen ohne Kompromisse zu liefern. Von neuen Builds und Redesigns bis hin zu Migrationen und langfristigem Support liefern unsere Drupal-Experten Ergebnisse auf Enterprise-Niveau mit der Aufmerksamkeit einer Boutique-Agentur.

Buchen Sie noch heute einen Termin, und lassen Sie uns Ihre Drupal-Roadmap in eine leistungsstarke Realität verwandeln.