GraphQL servers

GraphQL lets the client ask for exactly the fields it needs in one request.

🔎 Unravel this example Prerequisites (1)

Learn these first

Spring REST controllers

At a glance

Mental model

A buffet versus a fixed menu.

What happens, in order

1A schema file (schema.graphqls) defines types, Query and MutationIn Spring for GraphQL, @QueryMapping on a controller method resolves a query field, @MutationMapping a mutation, and @Argument binds arguments.
2@SchemaMapping(typeName = "Order", field = "customer") resolves a nested field, called only if the client asked for it
3A single request can combine many fields; the engine calls your fetchers for each requested path and assembles the JSON response
4Errors are returned in an errors array alongside partial data, with HTTP status 200, so clients must check the body

Remember

Resolving a nested field per parent item (50 orders, each fetching its customer) causes N+1 queries
Clients can write expensive queries (deep nesting, huge lists)
graphql-java parses and validates the query against the schema, then executes it breadth-first level by level, calling a DataFetcher per field (possibly asynchronously)

Watch out

N+1 fetching of nested fieldsNo depth or complexity limitsTreating HTTP 200 as successAuthorisation only at the top-level query

Example (highlighted lines explain it)

@Controllerpublic class OrderGraphQl {    @QueryMapping    public Order orderById(@Argument String id) {        return orders.findById(id).orElse(null);    }    @BatchMapping    public Map<Order, Customer> customer(List<Order> orders) {        return customers.loadFor(orders);    }}

line 3 uses QueryMapping, the core of GraphQL servers
line 4 uses Argument, the core of GraphQL servers
line 8 uses BatchMapping, the core of GraphQL servers

Read the full explanation (about 2 min)

GraphQL lets the client ask for exactly the fields it needs in one request. The server describes its types in a schema and provides a fetcher for each field, which makes the N+1 problem the main thing to manage.

A mental model

A buffet versus a fixed menu. The REST menu gives you the same plate every time; with GraphQL you walk along and pick precisely the items you want, and the kitchen has to fetch each one.

How it works

A schema file (schema.graphqls) defines types, Query and Mutation. In Spring for GraphQL, @QueryMapping on a controller method resolves a query field, @MutationMapping a mutation, and @Argument binds arguments.

@SchemaMapping(typeName = "Order", field = "customer") resolves a nested field, called only if the client asked for it.

A single request can combine many fields; the engine calls your fetchers for each requested path and assembles the JSON response.

Errors are returned in an errors array alongside partial data, with HTTP status 200, so clients must check the body.

Going deeper

Resolving a nested field per parent item (50 orders, each fetching its customer) causes N+1 queries. @BatchMapping or a DataLoader collects the keys and loads them in one call.

Clients can write expensive queries (deep nesting, huge lists). Limit query depth and complexity, page every list, and use persisted queries in public APIs.

Authorise at the field and data level, not only the endpoint. Introspection should be off in production unless it is a public API.

Under the hood

graphql-java parses and validates the query against the schema, then executes it breadth-first level by level, calling a DataFetcher per field (possibly asynchronously). DataLoaders defer loading until the level is complete so that keys requested from many parents are batched into one call.

Common mistakes

N+1 fetching of nested fields.
No depth or complexity limits.
Treating HTTP 200 as success.
Authorisation only at the top-level query.

How Unravel recognises it

When you paste code, Unravel looks for these signs of graphql servers. Spotting them yourself is a good habit when you read unfamiliar code:

Annotations: @QueryMapping @MutationMapping @SubscriptionMapping @SchemaMapping @BatchMapping @DgsComponent @DgsQuery @DgsMutation @DgsData @Argument
Types: DataFetcher DataFetchingEnvironment DataLoader DataLoaderRegistry GraphQL GraphQLSchema RuntimeWiring GraphQlSource GraphQlTester HttpGraphQlClient GraphQLError DgsQueryExecutor

Part of a learning path

Building and documenting APIs · previous: Custom Jackson serialization and modules · next: gRPC services and clients

Related concepts

Spring REST controllersSpring Lazy loading and the N+1 query problemPersistence

Frequently asked questions

What is GraphQL servers?

What are the most common mistakes with GraphQL servers?

N+1 fetching of nested fields. No depth or complexity limits. Treating HTTP 200 as success. Authorisation only at the top-level query.

How can I see GraphQL servers in real code?

Paste your own Java into Unravel and it will point out where graphql servers appears, explain how it works at the detail level you choose, and draw the flow of the code around it.