GraphQL Overview: From Schema to Federated API
A walk through GraphQL – from the typed schema through queries and resolvers to real time, operations and federated architecture, assessed as of October 2024.
GraphQL Overview: From Schema to Federated API
A typed schema and at least one Query entry point are enough to ask very different questions of a GraphQL API. These operations often run over an HTTP endpoint; the GraphQL specification itself, however, doesn’t prescribe the transport. The crucial question behind it is who determines the shape of the response. With a classic REST interface, the server defines the representation of a route. GraphQL lets the client select the fields it needs from it. Control stays with the backend, because every allowed selection is fixed in the schema beforehand.
This post walks the path from schema to distributed architecture once all the way through, so that you know the stations before you get lost in one of them. For individual stations – how exactly execution works internally – I write separate, deeper posts, such as GraphQL Concepts: Schema, Resolvers, Execution. Here it’s about the whole picture, with the tooling as of October 2024: Apollo Server 4 serves as the Node.js example, and the federation section refers to Apollo Federation 2. GraphQL over HTTP was a stage 2 draft specification back then and still is in July 2026; it describes the HTTP semantics for queries and mutations, not the transport of subscriptions.
GraphQL connects several responsibilities without turning them into a single building block.
From need to resolved response
- Client operation · describes the shape of the response it needs
- Schema · limits types, fields and allowed operations
- Execution · validates and plans the requested selection
- Resolver · resolves exactly one field within its context
- Data source · owns data and domain rules behind the resolver
- Gateway · can coordinate several subgraphs under one contract
The schema remains the contract and the point of orientation. It replaces neither the domain logic nor the data ownership of the connected systems.
GraphQL is a specification, not a framework#
The most common misconception at the start: GraphQL is a library you install. It isn’t. GraphQL is a specification – it describes a query language and how a server has to evaluate such a query. There are reference implementations such as graphql-js, and servers like Apollo Server or GraphQL Yoga build on them, but the heart of it is a contract, not a runtime.
Almost everything else follows from this one fact. Because the contract is typed, the client can know before the first call which fields exist and what type they have. And because the server evaluates the selection instead of just delivering a fixed representation, a shared HTTP endpoint can answer many different questions. A single endpoint is the common way to deploy it, not a requirement of the transport-agnostic specification.
flowchart LR
Client["Client<br/>formulates the question"] -->|one query| Endpoint["one GraphQL endpoint"]
Endpoint --> Engine["Execution<br/>against the schema"]
Engine --> DB[("Database")]
Engine --> REST["REST API"]
Engine --> Service["other service"]
Engine -->|exactly the requested fields| ClientWhat matters here: anything can sit behind that one endpoint. GraphQL is not a database and doesn’t replace one – it is a layer that brings different sources together under a shared, typed model.
The schema first#
Everything starts with the schema. It is written in the Schema Definition Language, SDL for short, and describes the types and their relationships. A small example from the world of a blog:
type Author {
id: ID!
name: String!
posts: [Post!]!
}
type Post {
id: ID!
title: String!
author: Author!
}
type Query {
author(id: ID!): Author
posts: [Post!]!
}
Three things are worth a close look. First, the modifiers: the exclamation mark means “must not be null”, the square brackets mean “list”. So [Post!]! is a non-nullable list of non-nullable posts – a very precise statement a client can rely on. Second, the relationships: Author refers to Post and vice versa. The schema doesn’t describe a flat catalog but a graph of nodes and edges – hence the name.
Third, and this is the core: Query is a special type. Optionally, Mutation for writing and Subscription for ongoing results are added. These operation types are the entry points into the graph. Anything that isn’t listed there as a field can’t be selected by any client. This makes the schema a real contract: it states bindingly which operations and response shapes are allowed.
Two tools make this contract much easier to handle in daily work. Fields can be marked as deprecated with @deprecated(reason: "…") without removing them right away – clients get the hint but don’t break. And for mutations there are dedicated input types, so that inputs aren’t confused with output types. Both are small signs that GraphQL is meant for long-lived APIs, not for the throwaway endpoint.
The query side: the client asks precisely#
A query looks similar to the data part of the response it produces. You describe the desired selection, and the successful response follows this shape:
query AuthorWithPosts($id: ID!) {
author(id: $id) {
name
posts {
title
}
}
}
Here the client asks for an author’s name and the titles of their posts – and gets only that. No superfluous field, no second round trip for the posts. The $id is a variable; queries are not parameterized by string fiddling but through typed variables that the server checks.
Two more building blocks show up quickly. Fragments bundle recurring sets of fields so that you don’t repeat them in every query. And introspection lets you query the schema itself – the server describes itself, which is why tools like GraphiQL can offer autocompletion and documentation without additional configuration. So the contract is not only binding, it is also readable.
Execution: resolver by resolver#
How does a query become a response? The server walks through the query from top to bottom and calls a function for each field, the resolver. Each resolver receives four arguments in a fixed order: the parent object (source), the field’s arguments (args), a request-scoped context (context) and information about the execution state (info).
const resolvers = {
Query: {
author: (source, { id }, context) => context.db.loadAuthor(id),
},
Author: {
posts: (author, args, context) => context.db.loadPostsForAuthor(author.id),
},
};
You can see the principle: the resolver for author returns an author, and its return value becomes the source for the field resolvers below it – the resolver for posts gets the author as its first argument and uses it to load the posts. This way, execution moves through the graph as a chain. A resolver can work synchronously, with a promise or async, and can talk to any data source – a database, a REST API, another service.
This is exactly where the best-known trap lurks, the N+1 problem. If someone queries ten authors with their posts, the posts resolver runs ten times and makes ten individual database queries – plus the one for the authors. The solution is batching: you collect the ten requests within one execution tick and answer them with a single query. The usual library for this is DataLoader.
flowchart TB
subgraph Ohne["Without DataLoader (N+1)"]
Q1["10 authors"] --> R1["10× posts resolver"]
R1 --> DB1[("10 individual queries")]
end
subgraph Mit["With DataLoader"]
Q2["10 authors"] --> R2["10× posts resolver"]
R2 --> L["DataLoader collects IDs"]
L --> DB2[("1 batched query")]
endHow execution runs through the tree in detail, in which order sibling fields are evaluated and why mutations are treated differently from queries – that’s a topic of its own, to which I dedicate a separate, deeper section in the concepts post. For this overview, it’s enough to know: a query is a path through the graph, and every node on the path is served by a resolver.
Writing and real time#
Reading is only half the story. Mutations are the writing part and look like queries, but they carry an intent:
mutation CreatePost($input: PostInput!) {
createPost(input: $input) {
id
title
}
}
The difference is more than cosmetic: at the top level, the server executes mutations one after another, not in parallel, so that two writes don’t get in each other’s way. And because a mutation returns a result – here the created post – the client can update its state directly from the response without reloading.
For ongoing updates there are subscriptions. The client subscribes to an event, and the server sends new data as soon as it arises. Classically this ran over WebSockets; by now, transport over server-sent events is common too, especially when a simple, one-way connection is enough – I have written more about this elsewhere. The GraphQL over HTTP draft spells out the HTTP semantics for queries and mutations so that servers and clients from different vendors work together more reliably. Subscriptions are explicitly outside its scope.
Operations: errors, pagination, auth, caching#
Between the first working schema and an API that holds up in production lie a few topics you shouldn’t skip.
GraphQL handles errors in its own way: a response can contain data and an errors field at the same time. A failed subfield doesn’t break the whole response – the rest still arrives. That is powerful, but it demands discipline so that clients can tell expected errors from real failures.
Pagination is rarely solved with simple offset/limit arguments, but mostly with cursor-based connections – the connections pattern with edges and page info, which comes from the Relay world and has established itself as a convention. It is a bit more cumbersome to read, but stable when the list changes under your fingers.
Authentication and authorization are not the same thing. The identity is often determined when the context is built and passed on from there to execution. The actual access rules can live in resolvers, directives, the domain layer or the data access layer. What matters is that every relevant access point enforces the same policy instead of merely trusting that a field stays hidden in the schema.
Finally, caching is different from many REST APIs, where URL and HTTP method form an obvious cache key. GraphQL over HTTP can use HTTP caching as well, but different operations often share the same address and often sit in the request body. Clients like Apollo Client therefore add a normalized object cache: objects with a stable identity can be updated together across several queries.
Architecture: a layer that aggregates#
This brings us to GraphQL’s real strength at scale. Because any source can sit behind the endpoint, GraphQL is excellent as an aggregation layer – a backend for frontend that pulls several services, databases and third-party APIs together under one model, tailored to what the UI really needs.
flowchart TB
App["Web & mobile client"] --> GW["GraphQL gateway<br/>(federated schema)"]
GW --> S1["Subgraph: users"]
GW --> S2["Subgraph: orders"]
GW --> S3["Subgraph: catalog"]
S1 --> DB1[("Users DB")]
S2 --> DB2[("Orders DB")]
S3 --> REST["Catalog REST"]If the schema becomes too big for a single team, federation comes into play. Instead of a monolith, each team runs its own subgraph, and a gateway assembles them into a single, coherent schema for the client. The client notices nothing of this – it still sees one graph. Federation is today the usual way when GraphQL has to scale organizationally; you still find the older schema stitching approach in existing systems.
When it comes to choosing a server, the field has sorted itself out. Apollo Server 4 is the safe default choice for an ordinary Node.js stack – the largest ecosystem, good federation support, broad use in practice. GraphQL Yoga is the leaner alternative, especially when you deploy to edge runtimes where Apollo Server would be too heavyweight. Both rely on graphql-js version 16 as their shared foundation.
The repository as a common thread#
If you want to get hands-on with all of this, you’ll find the stations as individual chapters in introduction-graphql – from intro, architecture and principles through schema, types and resolver to mutations, subscriptions, paging, auth and caching. On top of that there are runnable examples: an Apollo monorepo, a server in C# as evidence that GraphQL is language-independent, and a folder with recipes for recurring tasks – DataLoader, pagination, auth, optimistic UI, server-side rendering. The chapters are deliberately cut so that each can be read on its own, and that’s exactly how this post is meant too.
What should stick#
If one sentence from this overview should stick, it is this one: GraphQL is first a question of API design and only then a question of tooling. The schema is the contract, the resolvers are the implementation, and everything on top – federation, caching, the concrete server – is the execution of this one idea that the client asks its question and the backend keeps an explicit model.
The tools will keep changing; Apollo Server 4 won’t be the last generation, and the next one is sure to come. What remains is the typed schema and execution along the graph. There are separate posts on individual stations – how execution works internally and how to design a schema that grows.
Further reading#
- Repository introduction-graphql (chapters, Apollo example, recipes): https://github.com/mikebild/introduction-graphql
- Slide overview for this post: https://slides.mikebild.dev/introduction-graphql.en.html
- GraphQL, official introduction: https://graphql.org/learn/
- GraphQL specification: https://spec.graphql.org/
- GraphQL over HTTP: https://graphql.github.io/graphql-over-http/
- Apollo Server, documentation: https://www.apollographql.com/docs/apollo-server
- DataLoader (batching against N+1): https://github.com/graphql/dataloader
Revised and translated from German with the help of AI.