GraphQL Debugging with Altair, GraphiQL, Insomnia, and Postman

1. Why GraphQL debugging works differently than REST testing

REST debugging typically means: call a URL, choose an HTTP method, check the response. GraphQL concentrates all operations on a single endpoint, which changes the tool selection. Instead of URL variation, you need schema exploration, a query builder with autocomplete, and the ability to quickly formulate structured JSON bodies with nested queries. Tools that only understand HTTP requests work fine for simple GraphQL calls, but they offer no schema support.

Another difference: GraphQL returns HTTP 200 even when there is an error. The error sits in the errors array of the JSON body, not in the HTTP status code. That means tools that react only to HTTP status codes treat GraphQL errors as success. Anyone who overlooks this ends up debugging in the wrong place. Good GraphQL debugging tools parse the response and display errors from the errors array separately.

2. GraphiQL: The embedded browser standard

GraphiQL is the reference explorer for GraphQL that runs directly in the browser and can optionally be served by most GraphQL servers, including Magento. It offers schema exploration via the sidebar, autocomplete while typing a query, and direct execution against the configured endpoint. For quick experimentation on your own development server without installing an extra tool, GraphiQL is the first choice.

GraphiQL's limits lie in auth configuration. Standard GraphiQL has no built-in UI for persistent HTTP headers. Anyone who needs to set a bearer token depends on browser plugins or custom GraphiQL setups with header support. The more modern GraphiQL v2 variant ships with header configuration, but it is not available everywhere. In Magento projects, Magento's own GraphQL playground (/graphql with the explorer enabled) is a good alternative that provides Magento context directly.

# Typical GraphiQL workflow: schema exploration then query execution

# Step 1: explore available queries via schema sidebar
# Step 2: use autocomplete to build the query

query ExploreCustomerType {
  customer {
    # Autocomplete shows all available fields from Customer type
    firstname
    lastname
    email
    orders {
      items {
        order_number
        status
        grand_total { value currency }
      }
    }
  }
}

# Step 3: set variables in the Variables panel
# { }  no variables needed for this query

# Step 4: add Authorization header in Headers panel (GraphiQL v2):
# { "Authorization": "Bearer <customer-token>" }

3. Altair GraphQL Client: Desktop power for complex scenarios

Altair is a desktop app (available for macOS, Windows, and Linux, as well as a browser extension) designed for daily GraphQL debugging work. It offers persistent header configuration, environments for different stages (local, staging, production), collections for frequently used queries, and an integrated schema documentation browser. Anyone working with GraphQL APIs on a daily basis will appreciate Altair as a complete tool.

Particularly useful for Magento debugging: Altair lets you configure environments with different bearer tokens, so you can switch easily between guest requests and authenticated customer requests. The History tab shows all recently sent queries, which makes reproducing bugs significantly easier. Altair's plugin system also enables schema diff visualizations and direct subscription support when the server offers WebSocket connections for GraphQL subscriptions.

4. Insomnia: GraphQL support in an API client context

Insomnia is a general-purpose API client that natively supports GraphQL. Unlike pure GraphQL tools such as Altair, Insomnia treats GraphQL as one of several request types alongside REST, gRPC, and WebSockets. That is an advantage for teams debugging REST and GraphQL in parallel, because all requests can be managed in a single tool interface.

Insomnia offers automatic schema introspection, autocomplete in the query editor, and variable panels. Auth configuration via bearer token, OAuth, and other methods is built in natively. A practical aspect for Magento debugging: Insomnia lets you save a generate-token request (a REST POST against Magento) and a GraphQL query in the same collection and run them one after another. That simplifies the auth workflow, where the token first has to be obtained and then inserted into the GraphQL request.

5. Postman: GraphQL in existing REST workflows

Postman has supported GraphQL for several years and is interesting for teams that already have an extensive Postman collection for REST endpoints and want to integrate GraphQL requests into the same system. The GraphQL schema gets imported into Postman, after which autocomplete becomes available in the query editor. Collection Runner, automated testing, and monitoring are Postman strengths that can also be used for GraphQL.

Postman's weakness in the GraphQL context lies in the depth of schema exploration. GraphQL-native tools such as Altair or GraphiQL offer more intuitive schema browsers and a better autocomplete experience. Postman is less suited for pure exploration sessions. For embedding GraphQL requests into existing CI/CD workflows and collections, however, Postman is well positioned, especially when the team already uses Postman for REST.

# Magento debugging workflow: token first, then authenticated query

# Step 1: get customer token (works in all tools as POST request)
# POST https://shop.example.com/graphql
# Content-Type: application/json
mutation GetToken {
  generateCustomerToken(email: "customer@example.com", password: "password123") {
    token
  }
}

# Step 2: use token in authenticated query
# Authorization: Bearer <token-from-step-1>
query DebugCustomerOrders {
  customer {
    firstname
    orders(pageSize: 5) {
      items {
        order_number
        status
        created_at
        grand_total { value currency }
        items {
          product_name
          quantity_ordered
          product_sale_price { value }
        }
      }
    }
  }
}

# If errors appear: check errors[] array, not HTTP status
# HTTP 200 does NOT mean success in GraphQL

6. Configuring auth headers: the token workflow in every tool

In all four tools, the bearer token has to be set as an HTTP header: Authorization: Bearer TOKEN. The difference lies in the UX: Altair and Insomnia offer dedicated header panels with persistence and environment variables. Postman allows auth configuration at the collection level, which automatically applies to all requests in the collection. GraphiQL, in its basic version, requires browser plugins or custom implementations for persistent headers.

For Magento projects with token expiry, an environment-based workflow makes sense: the environment stores the token as a variable, and a dedicated request fetches a new token and updates the variable. Altair supports this workflow with pre-request scripts, Insomnia with chained requests. Manually copying the token from a token request into a query request is error-prone and should be replaced with a structured workflow as soon as the debugging effort becomes a regular occurrence.

7. Magento-specific debugging: error sources and diagnostic workflow

Magento GraphQL errors follow specific patterns worth knowing. Resolver exceptions get converted into structured GraphQL errors and returned in the errors array of the response. In development environments, the extensions object often contains stack trace information that shows the origin of the error directly. In production environments this information is hidden, which is one more reason to reproduce bugs in development before they surface in production.

A common diagnostic problem in Magento: the query returns empty arrays or null without throwing an explicit error. That typically points to a visibility or permission problem, not a resolver bug. The debugging workflow: test the query first without an auth header (guest context), then test with a token and compare the responses. Differences reveal which fields depend on auth. Then check the Magento logs (var/log/system.log, var/log/exception.log) to find PHP errors that were not carried over into the GraphQL response.

8. Tool comparison: what makes sense when

No single debugging tool is optimal for every scenario. The strengths of the tools complement each other, and in practice you switch between them depending on context.

For Magento development, a combination is recommended: Altair for the daily development workflow with environments and collections, GraphiQL for quick schema checks directly in the browser, curl for CI scripts and automated verification steps. Postman makes sense when the team already maintains REST collections in Postman and wants to integrate GraphQL requests into the same context.

9. Common debugging mistakes and how to avoid them

The most common mistake in GraphQL debugging is treating HTTP 200 as a success signal. GraphQL always returns HTTP 200, even when the resolver has thrown an error. Anyone who overlooks this ends up debugging in the wrong place. All the tools mentioned display the errors array in the response, but only if you actively look for it. A good workflow: after every request, check the errors array first, before examining the data section.

A second common mistake is skipping the variables panel. Instead of embedding variables directly in the query, they should be entered as JSON variables in the Variables panel. Queries with embedded values are not parametrizable, harder to reuse, and can trigger JSON parsing errors with special characters such as quotation marks inside strings. All four tools offer a Variables panel, and it should be used consistently.

# WRONG: value embedded directly in query, not parametrizable
query {
  products(search: "Leather Handbag 42cm (brown)") {
    items { sku name }
  }
}

# RIGHT: variable in Variables panel, query parametrizable and reusable
query SearchProducts($search: String!, $pageSize: Int = 10) {
  products(search: $search, pageSize: $pageSize) {
    total_count
    items {
      sku
      name
      price_range {
        minimum_price {
          final_price { value currency }
        }
      }
    }
  }
}

# Variables panel:
# {
#   "search": "Leather Handbag 42cm (brown)",
#   "pageSize": 5
# }

# Checking errors array first, always before inspecting data:
# { "errors": [...], "data": { "products": null } }
# vs.
# { "data": { "products": { "total_count": 3, "items": [...] } } }

10. Summary

Efficient GraphQL debugging requires the right tool for the right context. GraphiQL is the fastest entry point for browser-based schema exploration. Altair is the most complete desktop tool for the daily debugging workflow with environments, collections, and history. Insomnia and Postman make sense when REST and GraphQL need to be managed in a single interface or when CI integration is required.

For Magento debugging, the core principles hold true regardless of the tool: HTTP 200 is not success, always check the errors array. Move variables into the Variables panel instead of embedding them in the query. Structure the auth workflow with environments to automate token handling. Compare responses between guest and customer context to tell visibility-related empty results apart from real errors.

11. FAQ: GraphQL Debugging with Altair, GraphiQL, Insomnia, and Postman