Magento 2 GraphQL API — wanneer en hoe inzetten

Magento 2 GraphQL API — wanneer en hoe inzetten

GraphQL in Magento 2 haalt gemiddeld 40% minder data op dan vergelijkbare REST-calls. Dat is geen marketingclaim — dat is de logica van het protocol. Je vraagt precies wat je nodig hebt, niet meer.

Maar de meeste Magento-implementaties gebruiken GraphQL verkeerd of helemaal niet. REST zit dieper in de codebase, is makkelijker te debuggen, en de documentatie is beter. Dat zijn begrijpelijke redenen om bij REST te blijven.

Toch is er een groeiende categorie use cases waarbij GraphQL de betere keuze is. Dit artikel legt uit welke, en hoe je het implementeert.

Wat je leert in dit artikel

• Het fundamentele verschil tussen GraphQL en REST in Magento 2
• Concrete use cases waarbij GraphQL wint
• Hoe je queries schrijft en uitvoert
• Performance-benchmarks: GraphQL vs REST
• Wanneer je gewoon bij REST blijft

GraphQL vs REST: het fundamentele verschil

REST geeft je endpoints terug. GraphQL geeft je een schema.

Bij een REST-call naar /V1/products/:sku krijg je het complete product-object terug — alle 80+ velden, ook de velden die je niet nodig hebt. Bij GraphQL definieer je zelf welke velden je wilt.

# REST geeft alles. GraphQL geeft dit:
{
  products(filter: { sku: { eq: "MH01" } }) {
    items {
      sku
      name
      price_range {
        minimum_price {
          regular_price {
            value
            currency
          }
        }
      }
    }
  }
}

Dit is het over-fetching probleem dat GraphQL oplost. Op een productdetailpagina heb je misschien 15 velden nodig uit een object met 80+ velden. REST stuurt alles. GraphQL stuurt precies wat je vraagt.

Het under-fetching probleem is het omgekeerde: REST vereist soms meerdere calls om alle benodigde data op te halen. GraphQL combineert dat in één query.

Wanneer gebruik je GraphQL in Magento 2?

Drie situaties waarbij GraphQL duidelijk wint van REST.

1. Headless frontend (PWA, React, Vue)

De primaire use case. Als je een PWA Studio, Vue Storefront, of eigen React-frontend bouwt bovenop Magento, is GraphQL de aangewezen API. Magento's PWA Studio is volledig gebouwd op GraphQL.

De reden is simpel: een SPA-frontend doet veel kleine API-calls. GraphQL minimaliseert de payload per call en staat meerdere resource-types toe in één request.

# Eén query voor productdata EN categorie-informatie
{
  products(filter: { category_id: { eq: "12" } }) {
    items {
      id
      name
      sku
      small_image {
        url
        label
      }
      price_range {
        minimum_price {
          regular_price {
            value
            currency
          }
        }
      }
      categories {
        name
        url_path
      }
    }
    page_info {
      current_page
      page_size
      total_pages
    }
    total_count
  }
}

Dit vervangt twee of drie REST-calls.

2. Mobile apps

Een mobiele app op een 4G-verbinding profiteert direct van kleinere payloads. GraphQL reduceert datatransfer met 30-60% vergeleken met REST, afhankelijk van het endpoint.

Bovendien kan een app per scherm exact de benodigde data opvragen. Het productoverzichtsscherm vraagt andere velden dan de productdetailpagina.

3. Complexe data-aggregatie

Soms wil je in één request data ophalen die anders meerdere REST-calls zou vereisen. GraphQL ondersteunt dit van nature.

# Klantdata, orders én wishlist in één call
{
  customer {
    firstname
    lastname
    email
    orders {
      items {
        number
        order_date
        status
        total {
          grand_total {
            value
            currency
          }
        }
      }
    }
    wishlist {
      items_count
      items_v2 {
        items {
          product {
            name
            sku
          }
        }
      }
    }
  }
}

GraphQL queries uitvoeren in Magento 2

Magento 2 GraphQL-endpoint is /graphql. Alle queries gaan via POST.

Basis-aanroep met cURL

curl -X POST \
  https://jouwshop.nl/graphql \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "{ products(search: \"shirt\") { items { sku name } total_count } }"
  }'

Geauthenticeerde calls

Voor klantspecifieke data (orders, wishlist, account) heb je een Bearer token nodig.

# Stap 1: token ophalen
mutation {
  generateCustomerToken(email: "[email protected]", password: "wachtwoord") {
    token
  }
}

# Stap 2: token meesturen
curl -X POST \
  https://jouwshop.nl/graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJhbGci...' \
  -d '{ "query": "{ customer { firstname email } }" }'

GraphQL in PHP (Magento module)

Als je een custom module bouwt die GraphQL-resolvers toevoegt, is dit de structuur:

<!-- etc/schema.graphqls -->
type Query {
    customProduct(sku: String!): CustomProductOutput @resolver(class: "Vendor\\Module\\Model\\Resolver\\CustomProduct")
}

type CustomProductOutput {
    sku: String
    naam: String
    voorraad: Int
}

<?php
// Model/Resolver/CustomProduct.php
namespace Vendor\Module\Model\Resolver;

use Magento\Framework\GraphQl\Config\Element\Field;
use Magento\Framework\GraphQl\Query\ResolverInterface;
use Magento\Framework\GraphQl\Schema\Type\ResolveInfo;

class CustomProduct implements ResolverInterface
{
    public function __construct(
        private readonly \Magento\Catalog\Api\ProductRepositoryInterface $productRepository
    ) {}

    public function resolve(Field $field, $context, ResolveInfo $info, array $value = null, array $args = null)
    {
        $sku = $args['sku'];
        $product = $this->productRepository->get($sku);

        return [
            'sku' => $product->getSku(),
            'naam' => $product->getName(),
            'voorraad' => (int) $product->getExtensionAttributes()->getStockItem()->getQty(),
        ];
    }
}

Performance-benchmarks: GraphQL vs REST

Wij hebben op een standaard Magento 2.4.7-installatie beide API's gemeten op een productdetailpagina-scenario.

De payloadverschillen zijn het opvallendst. REST stuurt data mee die de frontend nooit gebruikt. GraphQL niet.

Kanttekening: deze tijden zijn zonder Varnish. Met full page cache zijn REST en GraphQL vergelijkbaar snel voor gecachte responses. Het verschil speelt bij uncached of gepersonaliseerde requests.

Wanneer blijf je bij REST?

GraphQL is niet altijd beter. Er zijn situaties waarbij REST de betere keuze is.

Veelgemaakte fouten

Best practices

Conclusie

GraphQL in Magento 2 is geen hype. Het is een protocol met een specifiek toepassingsgebied: headless frontends, mobiele apps en situaties waarbij je meerdere resources in één call wilt ophalen.

Voor die use cases levert het meetbaar minder data, minder calls en betere performance. Voor server-to-server integraties en eenvoudige koppelingen is REST eenvoudiger en voldoende.

De keuze hangt af van je architectuur. Bouw je headless, kies GraphQL. Bouw je een standaard Magento-koppeling, blijf bij REST.

Meer weten over headless Magento-architectuur? Lees dan ook ons artikel over headless e-commerce: hype of business case. Of bekijk onze Magento 2 diensten voor een gesprek over jouw specifieke situatie. De officiële Adobe GraphQL API-documentatie bevat de volledige schema-referentie.