GraphQL is the API layer Adobe is investing in, and if you are building a headless storefront, a mobile app or a PWA on Magento 2, it is where you should start. Unlike the REST API, GraphQL lets the client ask for exactly the fields it needs in one round trip - which is why it dominates the headless ecosystem. This guide gets you from zero to a working custom query.
Exploring the Schema
Magento exposes a single endpoint at /graphql. Point a tool like GraphiQL or Altair at it and introspect the schema: you will find queries for products, categories, carts, customers and CMS content. A first query looks like this:
{
products(filter: { sku: { eq: "24-MB01" } }) {
items {
name
sku
price_range {
minimum_price {
final_price { value currency }
}
}
}
}
}
Notice how the response mirrors the query shape. No over-fetching, no second request for prices.
Queries vs Mutations
Reads are queries; writes are mutations. Cart operations are the canonical example: createEmptyCart, addProductsToCart, setShippingAddressesOnCart and placeOrder cover the whole checkout flow. Customer-facing mutations require the customer token from generateCustomerToken sent as a Bearer header.
Writing a Custom Endpoint
Custom modules extend the schema with a schema.graphqls file and resolver classes:
type Query {
storeHours(storeCode: String): StoreHours
@resolver(class: "Vendor\\Module\\Model\\Resolver\\StoreHours")
}
type StoreHours {
open: String
close: String
note: String
}
The resolver implements ResolverInterface, receives the arguments, and returns the data. Register nothing else - Magento picks up the schema file automatically on cache flush. Resolvers must implement getCacheIdentity if the result should be cached by the built-in GraphQL cache.
GraphQL vs REST: Choosing Sensibly
- Storefront and mobile: GraphQL. It is faster for composite screens and is what PWA Studio, Hyva frontends and Adobe’s own tools speak.
- Bulk integrations (ERP stock feeds, order export): REST or the asynchronous bulk REST API. GraphQL is not designed for ten-thousand-row sync jobs.
- Legacy integrations: REST’s stable service contracts remain the safer target.
Production Notes
Enable the built-in GraphQL query cache for anonymous traffic - product and category queries cache extremely well. Watch out for deep, expensive queries from clients; set query depth and complexity limits at the edge (Fastly or your WAF) rather than discovering a denial-of-wallet query in production.
GraphQL is mature in Magento now: coverage gaps that once forced REST fallbacks have mostly closed. Start new frontend work on GraphQL, keep REST for bulk and legacy, and your API layer will stay coherent for years.