Magento 2 ships three entirely different API layers: REST, SOAP, and GraphQL. If you've worked with webapi.xml before, you already know REST and SOAP - this series is dedicated to the third layer: GraphQL. It's aimed at developers with PHP knowledge who want to write their own queries and mutations, extend existing ones, and understand the typical performance pitfalls.

GraphQL in a nutshell

GraphQL is a query language for APIs, originally developed at Facebook, an open specification since 2015. Unlike REST, GraphQL has no resource URLs and no HTTP verbs for different operations - there is exactly one endpoint (in Magento: /graphql), to which requests are practically always sent via POST. The client describes in the request itself which fields it wants to see - no over- or under-fetching problems, because the response matches the requested structure exactly.

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

This request returns exactly name, SKU, and price range for two products - no more, no less. A REST equivalent would either have to return a fixed response format with many unused fields (overfetching) or call multiple endpoints in sequence to assemble nested data such as price ranges (underfetching plus multiple roundtrips).

Why REST/SOAP aren't enough for every use case

REST and SOAP aren't bad in Magento - they're built for different jobs. The typical friction points GraphQL addresses:

• Overfetching: a REST endpoint like /V1/products/:sku always returns the full product representation, even if a mobile app only needs the name and price.
• Underfetching and roundtrips: nested data (product → category → related products) often requires several sequential REST calls, which noticeably costs latency on mobile connections.
• Versioning: REST endpoints grow over time or need new versions (/V2/...) when field requirements change. GraphQL schemas grow additively via extend type (block 3 of this series) without breaking existing clients.

Where Magento GraphQL is actually used

In practice, GraphQL in Magento is almost exclusively the storefront interface: it powers PWA Studio frontends, headless storefronts, and any app that wants to consume the product catalog, cart, checkout, or customer account. The classic Luma/Hyvä storefront in this project renders server-side and doesn't use GraphQL itself - that doesn't change the fact that the endpoint is active as soon as the matching core modules are installed.

The admin area, by contrast, stays with UI Components and REST (see the Admin Grids & Forms series) - GraphQL was never designed as a replacement for backend management. There are isolated exceptions where a GraphQL resolver is addressed with an admin token instead of a customer token (chapter 23), but that remains the exception, not the rule.

Three API layers side by side, not against each other

REST/SOAP are declared via webapi.xml, GraphQL via schema.graphqls - two completely separate configuration layers that can both build on the same service contracts (repositories, Api/Interfaces). A well-cut repository can easily be reused both from a REST controller and from a GraphQL DataProvider - this series demonstrates that from block 4 onward, using a custom events API as the example.

Chapter 2 shows which building blocks Magento's GraphQL architecture actually consists of - schema.graphqls, resolvers, and DataProviders - before chapter 3 moves on to the first custom query against the existing endpoint.