Cutting Over‑Fetch in Magento 2: A Practical Guide to GraphQL for Headless Front‑Ends

Problem: Over‑Fetching in Headless Magento Stores

When building a headless storefront on top of Magento 2, developers often hit the same performance wall: the client pulls more data than it actually needs. A REST call to /V1/products returns a fixed payload that includes thousands of fields, even if the page only displays the product name, price, and image. The extra data increases payload size, slows the first paint, and forces the client to filter out unwanted fields.

How can the front‑end request only the fields it needs without rewriting the entire API layer?

Thesis: GraphQL Gives You Field‑Level Precision

Magento 2’s GraphQL API lets a client specify exactly which product attributes to retrieve. A single request can replace many REST calls, and pagination is built into the schema. The result is leaner payloads, faster page loads, and a cleaner client code base.

1. Why GraphQL in Magento?

• Selective Data Retrieval: Clients declare the shape of the data they need.
• Single Endpoint: All data lives under /graphql, eliminating the need for multiple REST URLs.
• Pagination & Filtering: The schema exposes pageSize and currentPage arguments, plus filters for categories, attributes, and price ranges.
• Cache‑Friendly: Magento’s Varnish or Redis layers can cache GraphQL responses if you enable the X-GraphQL-Cache header.

2. Core Schema Overview

Magento’s GraphQL schema is generated from the app/code/Magento/GraphQl/etc/schema.xml files. Key entry points for product data include:

• products – a connection type that returns a list of Product objects.
• product – fetch a single product by sku or id.
• categoryList – retrieve categories and their child categories.
• Custom attributes defined in app/code///etc/graphql are automatically added to the Product type.

3. A Concrete Query Example

Below is a typical query that a React or Vue headless client might send. It fetches the first 10 products in a category, pulling only the fields the UI needs and a custom attribute called color.

query GetCategoryProducts($categoryId: Int!, $pageSize: Int = 10, $currentPage: Int = 1) {
  categoryList(filters: {category_id: {eq: $categoryId}}) {
    items {
      id
      name
      url_key
      url_suffix
      products(
        pageSize: $pageSize
        currentPage: $currentPage
      ) {
        items {
          sku
          name
          price {
            regularPrice {
              amount {
                currency
                value
              }
            }
          }
          media_gallery {
            url
            label
          }
          custom_attributes {
            attribute_code
            value
          }
        }
        page_info {
          total_pages
          current_page
        }
      }
    }
  }
}

**Where to run**: POST to /graphql on the Magento instance. Permissions: the client must be authenticated if the store uses customer‑only product visibility. The request body contains the query string and a variables object:

{
  "query": "...",
  "variables": {
    "categoryId": 42
  }
}

**Expected checks**:

• The response JSON should contain a data.categoryList.items[0].products.items array with the requested fields.
• Verify that custom_attributes includes an entry with attribute_code": "color" if the attribute exists.
• If the query fails with max depth exceeded, adjust max_query_depth in app/etc/di.xml.

4. Trade‑offs & Limitations

1. Depth Limits

   Magento enforces a default maximum query depth of 12. Deeply nested queries (e.g., product → price → regularPrice → amount) can hit this limit. Adjust the setting in app/etc/di.xml:

   <type name="Magento\GraphQl\Model\Resolver\Query\Config">
     <arguments>
       <argument name="max_query_depth" xsi:type="int">20</argument>
     </arguments>
   </type>

   After changing, run bin/magento setup:di:compile and clear caches.

2. Cache Invalidation

   Unlike REST, GraphQL does not automatically tie into Magento’s full‑page cache. To enable caching, set the X-GraphQL-Cache header to 1 and configure Varnish to respect it. Be cautious: a cached GraphQL response may become stale if product data changes frequently.

3. Custom Schema Changes

   Adding a new custom attribute to the GraphQL schema requires placing a graphql.xml file in app/code///etc and redeploying static content. Failure to do so means the attribute will not appear in queries.

4. Server Load

   Complex queries with many nested fields can increase CPU usage. Monitor var/log/debug.log for query execution times and adjust caching or query complexity accordingly.

5. Actionable Checklist

1. Define the exact product fields your UI needs.
2. Create a GraphQL query that requests only those fields.
3. Test the query in the GraphiQL playground (/graphql?debug=1) and verify the response shape.
4. Check max_query_depth and adjust if the query fails.
5. Enable X-GraphQL-Cache header and configure Varnish to cache responses.
6. For custom attributes, add graphql.xml, run bin/magento setup:static-content:deploy, and reindex.
7. Monitor performance with var/log/debug.log and var/log/varnish.log to ensure cache hits.
8. Document the query and its variables in your front‑end codebase.

By following this flow, a headless Magento store can deliver only the data it needs, reduce payload sizes, and keep the client logic simple.