This article was written in collaboration with @chanda_rajkumar
Introduction
When we write a GraphQL query and click “Send”, the server returns exactly the data we asked for - often in a single response.
But what actually happens behind the scenes?
How does the request travel from the client to the server?
How does GraphQL understand the query?
How does the server fetch and assemble the correct data?
Understanding this internal flow is important for developers because it helps in:
- Debugging API issues
- Designing efficient queries
- Building scalable backend systems
In this article, we will walk through the complete lifecycle of a GraphQL request, from the moment a client sends a query over HTTP to the final JSON response returned by the server.
Why GraphQL?
Before understanding how GraphQL works, it is helpful to understand why it was created.
Traditional REST APIs expose multiple endpoints such as:
This leads to two common problems:
Overfetching: The client receives more data than required.
For example, if an API returns a full user object but the UI only needs the user’s name, unnecessary data is transferred.
Underfetching: The client must make multiple API calls to gather all required data.
For example:
- Fetch users
- Fetch posts for each user
- Fetch comments for each post
This increases latency and network usage.
GraphQL solves this problem by allowing the client to request exactly the required data in a single query.
What is GraphQL?
GraphQL is a query language for APIs and also a runtime for executing those queries.
Unlike REST APIs, where the server decides the response structure, GraphQL allows the client to define the shape of the response.
Notice how the response structure matches the query structure.
This predictability is one of GraphQL’s strongest features.
GraphQL Runs on Top of HTTP
GraphQL does not replace HTTP.
Instead, HTTP is used as the transport mechanism to send queries and receive responses.
Most GraphQL APIs expose a single endpoint:
POST /graphql
All operations, queries and mutations are typically sent to this endpoint.
This differs from REST, where each resource has its own URL.
Structure of a GraphQL HTTP Request
A typical GraphQL request is sent as JSON:
JSON
{
"query": "...",
"variables": {...},
"operationName": "..."
}
query:Defines what data the client wants.
variables: Provide dynamic values to the query.
id, name, email
operationName: Used when multiple operations exist.
Understanding this structure is important because it represents the contract between client and server.
HTTP Methods in GraphQL
GraphQL typically uses:
POST → for queries and mutations
POST /graphql
Content-Type: application/json
GET → optionally for queries (useful for caching)
GET /graphql?query={users{name}}
The Journey of a GraphQL Request
Now let’s walk through what happens inside the server when a request is received.
1. Client Sends a Query
The client application (browser, mobile app, API tool) sends a GraphQL query.
This query represents the data requirements of the UI.
This query is usually sent as part of an HTTP request.
http://localhost:4000/graphql?query={users{name,email}}
2. HTTP Request Reaches the Server
The query is transported using an HTTP request.
POST /graphql
Content-Type: application/json
Request body:
{ "query": "{ users { name } }" }
At this stage, authentication middleware may run, headers and request context are read.
3. Request Reaches the /graphql Endpoint
The server receives the request at a single GraphQL endpoint, usually:
/graphql
Unlike REST APIs that use multiple endpoints, GraphQL routes all requests through this one endpoint.
At this stage:
- Authentication middleware may run
- Request context is prepared
- The request is handed over to the GraphQL execution engine
This is the entry point into GraphQL processing.
4. Query Parsing
GraphQL converts the query string into an internal structure (similar to a tree).
This allows GraphQL to understand:
- Which fields are requested
- How data is nested
- What arguments are provided
This step is similar to how compilers parse programming languages.
5. Schema Validation
GraphQL validates the query against the schema.
It checks:
- Whether fields exist
- Whether argument types are correct
- Whether the query structure is valid
If validation fails, execution stops and an error response is returned.
6. Execution Begins
If validation succeeds, GraphQL begins executing the query.
GraphQL starts executing the query field by field.
It determines:
- Which resolvers must run
- How nested fields should be resolved
7. Resolvers Fetch Data
Resolvers are responsible for fetching actual data.
They may query databases, call REST APIs, interact with microservices, apply business logic.
For nested queries, GraphQL automatically runs additional resolvers.
This enables GraphQL to fetch deeply related data in a single request.
8. Response is Constructed
Once all resolvers finish execution, GraphQL:
- Collects the resolved data
- Arranges it according to the query structure
- Constructs the final JSON response
If some fields fail, GraphQL may still return partial data along with errors.
One important feature is partial success, where some fields can return data while others return errors.
HTTP Status Codes in GraphQL
In traditional REST APIs, HTTP status codes usually indicate whether a request was successful or failed.
For example:
200 OK → request succeeded
404 Not Found → resource not found
500 Internal Server Error → server failure
However, GraphQL behaves slightly differently. Even if some fields in a query fail, the server may still return:
HTTP 200 OK
because GraphQL includes error details inside the response body.
Example
Suppose a client sends the following query:
Now imagine that the name field is successfully fetched, but fetching email fails due to an authorization issue.
The server might still respond with:
And the HTTP status code could still be:
HTTP 200 OK
This is because GraphQL allows partial success, where some parts of the query succeed while others return errors.
Conclusion
Understanding how GraphQL requests are processed helps developers build better APIs and debug issues more effectively.
Once you understand the request lifecycle from HTTP transport to resolver execution.
GraphQL becomes much easier to reason about and use in real-world applications.
Top comments (0)