Adobe Commerce development
Storefront design
Performance & SEO
AI & agentic commerce
Release tracker
Use Magento GraphQL for storefront work: headless front ends, mobile apps and anything a shopper's device calls directly. Use REST for back-office and system-to-system work: admin operations, ERP and PIM integrations, and bulk imports through the asynchronous bulk endpoints. Most real Adobe Commerce and Magento Open Source projects use both. The mistake is forcing one API to do the other's job.
The short version
- GraphQL lets the client ask for exactly the fields it needs in one request. Adobe positions it for headless storefronts and mobile apps. Queries sent with GET can be cached by Varnish or Fastly.
- REST exposes fixed endpoints for resources such as products, orders, customers and stock. It has broad admin coverage, mature token and OAuth authentication for integrations, and asynchronous and bulk variants backed by the message queue.
- SOAP still exists in Magento 2 but is rarely chosen for new work.
How Magento GraphQL works
Commerce exposes a single /graphql endpoint. Clients send queries (reads) and mutations (writes) against a typed schema that covers catalog, cart, checkout, customer accounts and, on Adobe Commerce, B2B features. A product listing page can fetch names, prices, images and stock in one round trip instead of several REST calls.
A simple product query looks like this:
query { products(filter: { sku: { eq: "SAMPLE-SKU" } }) { items { name sku price_range { minimum_price { final_price { value currency } } } } } }Caching matters. Adobe's GraphQL caching documentation states that only queries sent with HTTP GET are cached; POST queries and mutations are not. The X-Magento-Cache-Id header lets logged-in customers who share the same pricing context reuse cached results, and it is designed for Varnish or Fastly rather than the built-in full page cache. If your storefront sends every query as POST, you are giving up the main performance advantage.
How Magento REST works
REST endpoints follow the pattern /rest/<store_code>/V1/<resource>. Each call returns a fixed shape. Authentication options documented by Adobe include integration tokens and OAuth 1.0a for third-party systems, plus admin and customer tokens. Integrations are created in the Admin under System > Extensions > Integrations, where you restrict which resources they can touch.
REST's big advantage for integrations is asynchronous and bulk processing. Prefix an endpoint with /async and Commerce queues the request and returns a bulk_uuid straight away. Use /async/bulk and you can send an array of the same operation, which Commerce splits into separate messages for the async.operations.all consumer. You then check progress at /V1/bulk/:bulkUuid/status.
POST /rest/async/bulk/V1/products [ { "product": { "sku": "SAMPLE-1", "price": 19.99 } }, { "product": { "sku": "SAMPLE-2", "price": 24.50 } } ]Bulk processing needs a message broker. For Magento 2.4.9 on-premises, Adobe lists RabbitMQ 4.3 or ActiveMQ Artemis 2 as supported. On Adobe Commerce as a Cloud Service the route order differs (/V1/async/bulk/...), so check Adobe's documentation for your deployment.
Use-case matrix: which API for what
This matrix covers the jobs teams most often ask about. "Primary" means the API we would start with; "Possible" means it works but is not the natural fit.
| Use case | GraphQL | REST | Why |
|---|---|---|---|
| Headless category and product pages | Primary | Possible | One request per view, field selection, GET caching via Varnish or Fastly |
| Headless cart and checkout | Primary | Possible | Cart and checkout mutations are designed for storefront clients |
| Customer account area in a PWA or app | Primary | Possible | Customer token plus tailored queries for orders, addresses, wishlists |
| Native mobile app | Primary | Possible | Smaller payloads on mobile networks |
| Admin-style operations (create invoices, shipments, credit memos) | Limited | Primary | REST covers sales and admin resources more completely |
| ERP order export and status updates | No | Primary | Integration auth, order and shipment endpoints, predictable payloads |
| Stock and price updates from ERP | No | Primary (async bulk) | Queued bulk writes avoid timeouts and spread load |
| Catalog import from PIM | No | Primary (async bulk) or native import | Bulk endpoints or Commerce import for large catalogs |
| Combining Commerce with CMS or PIM data for a front end | Primary (via API Mesh) | As a mesh source | API Mesh exposes one GraphQL schema over many sources |
| Reporting and data warehouse extracts | No | Possible | Large extracts are often better as database replication or scheduled exports |
For integrations, our Magento ERP integration guide shows which data flows run in which direction and how often.
Performance and security differences
Performance
- GraphQL: fewer round trips, but a single deep query can be expensive. Use GET for cacheable queries and keep queries focused.
- REST: simple, predictable calls. For high volumes use async bulk endpoints instead of thousands of synchronous calls.
Security
- Give every integration its own credentials with only the resources it needs.
- Do not expose admin or integration tokens to browsers. Storefront clients should use guest or customer tokens only.
- Rate-limit public GraphQL at the CDN or web server layer, and watch for abusive query patterns.
Things that change on Adobe Commerce as a Cloud Service
Adobe's GraphQL documentation notes that the SaaS edition removes deprecated queries, mutations and fields, and replaces the core products and categories queries with service-based versions that are not backward compatible. Front ends built against PaaS GraphQL need updating before moving. It also notes that on PaaS, the core schema and service schemas (Catalog Service, Live Search, Product Recommendations) do not interact natively; combining them needs API Mesh.
Common mistakes
- Building ERP sync on GraphQL because the front-end team already knows it. Admin coverage and bulk processing are on the REST side.
- Synchronous REST loops for stock updates. Ten thousand single calls on a schedule will hurt performance. Use async bulk endpoints or a queue.
- POST-only GraphQL clients. They bypass caching. Use GET for cacheable queries.
- Custom endpoints for everything. Check the standard schema first. When you do need a custom endpoint, add it properly as a module with tests.
When you need a custom API
Both APIs are extensible. A module can add GraphQL types, queries and resolvers, or REST routes defined in webapi.xml backed by service contracts. Add custom endpoints only when the standard ones cannot express the operation, and version them like any public contract. On Adobe Commerce, out-of-process apps built with App Builder are another option for logic that should live outside the store.
FAQ
Is GraphQL replacing REST in Magento?
No. Adobe continues to document and extend both. GraphQL is the storefront API; REST remains the main integration API.
Which API should a headless storefront use?
GraphQL, with cacheable queries sent as GET and a CDN in front. Use REST only for gaps, and route them through your own back end, never with admin credentials in the browser.
Can I use both in the same project?
Yes, and most stores do: GraphQL for the front end and REST for ERP, PIM and other back-office systems.
Getting the API layer right
If you are planning a headless build, start with a list of pages and the fields each needs; that becomes your GraphQL plan. Mistri's headless Adobe Commerce services cover storefront API design, and our Magento extension development team builds custom GraphQL resolvers and REST endpoints when the standard schema is not enough.
Sources
Adobe Developer: GraphQL overview; Adobe Developer: GraphQL caching; Adobe Developer: REST bulk endpoints; Adobe Developer: Web API get started (authentication). Checked November 2026.
