GraphQL API query sequence
Client, server, and resolver layers in a GraphQL request.
GraphQL unifies client data fetching into a single query language, but understanding how that query flows through the layers — gateway validation, server parsing, resolvers fetching from data sources — is crucial for debugging performance issues and designing your API boundaries.
This template shows the happy path: a client sends a typed query, the gateway forwards it, the server parses and validates, resolvers fan out to the database, and the response comes back as a single JSON object with exactly the fields requested.
When to use this template
- API design reviews — lock in which resolvers fetch from which data sources before implementation, and agree on resolver boundaries and batching strategies.
- Onboarding new backend engineers — explain how a GraphQL query becomes a database query without requiring them to trace through the entire codebase.
- Performance troubleshooting — annotate each step with real latencies to find whether the bottleneck is in validation, resolution, or database queries.
How to adapt it
Rename participants to your real stack — Postgres, Redis, microservices, external APIs:
- Add batch loading — insert a DataLoader step before the database calls to collapse multiple single-row queries into one efficient batch.
- Include mutation — add a second sequence showing a mutation flow (input validation, resolver execution, database write, cache invalidation).
- Show subscription — append a WebSocket path showing how subscriptions push updates after mutations complete, extending the sequence for real-time patterns.
Visual edits regenerate clean Mermaid code, so you can paste the diagram into your GraphQL schema documentation or API runbook.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
sequenceDiagram
actor Client
participant Gateway as API Gateway
participant Server as GraphQL Server
participant Resolver as Resolver Layer
participant DB as Database
Client->>Gateway: POST /graphql (query)
Gateway->>Server: Forward query
Server->>Server: Parse & validate
Server->>Resolver: Execute query
Resolver->>DB: Fetch user data
DB-->>Resolver: User record
Resolver->>DB: Fetch related posts
DB-->>Resolver: Posts array
Resolver-->>Server: Resolved data
Server-->>Gateway: JSON response
Gateway-->>Client: Return fields
Frequently asked questions
- How is a GraphQL request different from a REST API call?
- REST requires multiple endpoints and round trips to fetch related data. GraphQL sends a single query describing exactly which fields you need — user name, profile picture, and posts together in one request. The server resolves all fields and returns one JSON response, eliminating overfetching and under-fetching.
- What does the resolver layer do in GraphQL?
- Resolvers are functions attached to each field that fetch or compute its value. When you query for a user and their posts, one resolver fetches the user from the database, another resolver fetches the posts. Resolvers can call APIs, databases, caches, or compute values on the fly — the client sees the end result as a flat JSON object.
- Why do we need an API gateway in front of GraphQL?
- Gateways handle cross-cutting concerns: rate limiting, authentication, logging, request transformation, and traffic routing. They sit between clients and your GraphQL server, so you can enforce policies — API keys, CORS, size limits — without coupling those rules to your business logic.
- How do I optimize this sequence for production?
- Add caching at three levels: HTTP caching at the gateway (for repeatable queries), in-memory caching in the resolver (DataLoader batches queries and caches hits), and database query caching. Implement request timeout and max depth limits to prevent expensive nested queries. Add monitoring to track resolver latency and identify bottlenecks.