GraphQL definition
GraphQL is a query language and runtime for APIs, created at Facebook and open-sourced in 2015, that lets clients request exactly the data they need in a single request. A GraphQL server exposes a typed schema describing the available data, and clients write queries that mirror the shape of the response they want back.
How does GraphQL work?
A GraphQL API is defined by a schema written in a type language: an Order type with id, status, items and customer fields, for example. Clients send queries to read data, mutations to change it and subscriptions to receive real-time updates, usually all through a single endpoint. On the server, resolver functions fetch each field from databases, REST services or other sources and assemble the response.
A mobile order screen might send a query asking for order 4417 with only its status, total and each item's name. The response contains exactly those fields and nothing else, nested in the same shape as the query. A REST client might need three calls, to the order, its items and its customer, and receive many fields it never displays.
GraphQL vs REST
REST exposes many endpoints, each returning a fixed shape. GraphQL exposes one typed graph that clients query flexibly, which removes over-fetching and under-fetching and lets frontend teams add fields without waiting for new endpoints. In exchange, GraphQL gives up simple HTTP caching, makes rate limiting by cost harder and adds a schema and resolver layer that must be designed and maintained carefully.
Key GraphQL concepts
Schema design is the most lasting decision. Model the schema around what clients need, such as products, carts and orders, rather than mirroring database tables, and evolve it by adding fields and deprecating old ones instead of versioning the whole API.
- Schema and types: the contract between client and server.
- Queries, mutations and subscriptions: read, write and real-time operations.
- Resolvers: functions that fetch the data for each field.
- Fragments: reusable sets of fields shared across queries.
- Introspection: clients and tools can ask the API to describe itself.
- Federation: combines schemas from several services into one graph.
Common GraphQL pitfalls
The classic performance trap is the N+1 problem: a query for 50 orders triggers one database call for the list and 50 more for each order's customer. Batching libraries such as DataLoader collapse those into a single query. Because clients can write deeply nested queries, servers also need depth and complexity limits to prevent expensive or malicious requests from overloading the database.
Caching needs a different approach. Persisted queries let a CDN cache known operations by ID, and client libraries cache normalized objects in the browser. Errors are another surprise: GraphQL often returns HTTP 200 with an errors array, so monitoring must inspect response bodies rather than status codes alone.
GraphQL tools and when to use it
Common servers include Apollo Server, GraphQL Yoga, Hot Chocolate for .NET and graphql-java, while Hasura and PostGraphile generate APIs directly from a database. On the client, Apollo Client, Relay and urql handle caching and state. GraphQL shines when several clients need different views of the same data, or when a frontend must combine many backend services. Nexzem typically uses it as a backend-for-frontend layer for apps with rich, varied screens.