Magento 2 bringt drei vollständig unterschiedliche API-Schichten mit: REST, SOAP und GraphQL. Wer schon mit webapi.xml gearbeitet hat, kennt REST und SOAP - diese Serie widmet sich der dritten Schicht: GraphQL. Sie richtet sich an Entwickler mit PHP-Kenntnissen, die eigene Queries und Mutations schreiben, bestehende erweitern und typische Performance-Fallen verstehen wollen.

GraphQL in Kürze

GraphQL ist eine Abfragesprache für APIs, entwickelt von Facebook, seit 2015 als Spezifikation offen. Anders als REST kennt GraphQL keine Ressourcen-URLs und keine HTTP-Verben für unterschiedliche Operationen - es gibt genau einen Endpunkt (in Magento: /graphql), an den Anfragen praktisch immer per POST geschickt werden. Der Client beschreibt in der Anfrage selbst, welche Felder er sehen möchte - keine Über- oder Unterfetch-Probleme, weil die Antwort exakt der angefragten Struktur entspricht.

query {
  products(search: "jacke", pageSize: 2) {
    items {
      name
      sku
      price_range {
        minimum_price {
          final_price { value currency }
        }
      }
    }
    total_count
  }
}

Diese Anfrage liefert exakt Name, SKU und Preisspanne für zwei Produkte - nicht mehr und nicht weniger. Ein REST-Äquivalent müsste entweder ein festes Response-Format mit vielen ungenutzten Feldern zurückgeben (Overfetching) oder mehrere Endpunkte nacheinander aufrufen, um verschachtelte Daten wie Preisspannen zusammenzusetzen (Underfetching plus mehrere Roundtrips).

Warum reicht REST/SOAP nicht für jeden Anwendungsfall?

REST und SOAP sind in Magento nicht schlecht - sie sind für andere Aufgaben gebaut. Die typischen Reibungspunkte, die GraphQL adressiert:

• Overfetching: Ein REST-Endpunkt wie /V1/products/:sku liefert immer die komplette Produktrepräsentation, auch wenn eine mobile App nur Name und Preis braucht.
• Underfetching und Roundtrips: Verschachtelte Daten (Produkt → Kategorie → verknüpfte Produkte) erfordern oft mehrere aufeinanderfolgende REST-Aufrufe, was auf mobilen Verbindungen spürbar Latenz kostet.
• Versionierung: REST-Endpunkte wachsen mit der Zeit oder brauchen neue Versionen (/V2/...), wenn sich Feldbedarfe ändern. GraphQL-Schemas wachsen additiv über extend type (Block 3 dieser Serie), ohne bestehende Clients zu brechen.

Wo Magento GraphQL tatsächlich einsetzt

In der Praxis ist GraphQL in Magento fast ausschließlich die Storefront-Schnittstelle: Sie treibt PWA-Studio-Frontends, headless Storefronts und jede App an, die Produktkatalog, Warenkorb, Checkout oder Kundenkonto konsumieren will. Der klassische Luma-/Hyvä-Storefront in diesem Projekt rendert serverseitig und nutzt GraphQL nicht selbst - das ändert nichts daran, dass der Endpunkt aktiv ist, sobald die passenden Core-Module installiert sind.

Der Adminbereich bleibt dagegen bei UI Components und REST (siehe die Admin-Grids-&-Formulare-Serie) - GraphQL wurde nie als Ersatz für die Backend-Verwaltung konzipiert. Es gibt vereinzelte Ausnahmen, bei denen ein GraphQL-Resolver mit einem Admin-Token statt einem Kunden-Token angesprochen wird (Kapitel 23), das bleibt aber die Ausnahme, nicht die Regel.

Drei API-Schichten nebeneinander, nicht gegeneinander

REST/SOAP werden über webapi.xml deklariert, GraphQL über schema.graphqls - zwei komplett getrennte Konfigurationsebenen, die beide auf denselben Service Contracts (Repositories, Api/Interfaces) aufsetzen können. Ein gut geschnittenes Repository lässt sich problemlos sowohl aus einem REST-Controller als auch aus einem GraphQL-DataProvider heraus wiederverwenden - diese Serie zeigt das ab Block 4 am Beispiel einer eigenen Veranstaltungen-API.

Kapitel 2 zeigt, aus welchen Bausteinen die Magento-GraphQL-Architektur konkret besteht - schema.graphqls, Resolver und DataProvider - bevor es in Kapitel 3 an die erste eigene Abfrage gegen den bestehenden Endpunkt geht.