What is GraphQL? A query language for APIs explained
GraphQL is a query language and runtime for APIs that lets a client ask for exactly the data it needs in a single request — addressing the over-fetching and under-fetching that can happen with traditional REST APIs. Rather than calling several fixed endpoints and receiving whatever shape each one returns, a GraphQL client describes the shape of the response it wants and receives precisely that back, no more and no less. It was developed at Facebook to serve complex mobile apps efficiently and has since been adopted well beyond that original setting. This guide explains the idea in plain terms, the problem it solves, how it works conceptually, and an honest comparison with REST — because, as with most tooling choices, neither is universally better.
The plain idea
With GraphQL, the client sends a query describing the exact fields it wants — say, a customer’s name and their three most recent orders’ dates and totals — and the server returns a response shaped to match that query, nothing extra attached. There is typically one endpoint for the whole API, rather than a different URL for every kind of resource; what varies between requests is the query, not the address.
This puts the client in control of the response shape in a way a fixed REST endpoint cannot: two different clients — a mobile app that wants a lean payload and a dashboard that wants everything — can query the very same API and each get back only what they asked for.
The problem it addresses
With a REST API (see our explainer on what a REST API is), each endpoint returns a fixed shape of data. If a screen needs a customer’s name plus their recent orders, you might over-fetch — receiving a large customer record when you only wanted the name — or under-fetch, needing a second call to a different endpoint to get the orders. Multiply that across a complex, deeply nested app and the number of round trips and unused fields adds up. GraphQL was built to remove that mismatch between what a UI needs and what a fixed endpoint happens to return, following the same underlying idea covered in our general API explainer: a defined contract, just a more flexible one.
How it works conceptually
Three ideas do most of the work:
- Schema — a strongly typed definition of every kind of data available and how it relates, which acts as the contract client and server agree on.
- Queries — a client sends a query describing exactly the fields and relationships it wants, and gets back JSON shaped to match.
- Mutations and subscriptions — mutations are how a client makes changes (the GraphQL equivalent of POST/PUT/DELETE), while subscriptions let a client receive ongoing updates for real-time data.
GraphQL versus REST, honestly
GraphQL’s strength is precise, flexible fetching, especially for complex or deeply nested data with many different client types pulling different slices of it. That flexibility comes at a cost: a GraphQL API is generally more complex to design and operate than a REST one, and caching is less straightforward, because REST’s cacheability leans on each resource having its own stable URL, while GraphQL’s single endpoint and client-shaped queries need their own caching strategies. REST, in turn, is simpler to build, easier to cache with standard web infrastructure, and perfectly adequate when a client’s data needs are fairly uniform. Neither is universally better — the right choice depends on how varied your clients’ data needs are and how much operational complexity you are willing to take on.
Where GraphQL is used
GraphQL tends to appear where an API serves several very different clients — web, mobile, third-party integrations — each wanting a different slice of a rich, interconnected data model, or where a UI is built from many small components that each need their own small piece of data. Cloud providers offer managed GraphQL tooling: AWS AppSync, for instance, provides a managed GraphQL API layer that can connect to databases, other AWS services and custom logic without you running the GraphQL server yourself.
GraphQL in certification study
GraphQL appears as one option among several for building APIs on AWS, most relevantly in the Developer Associate exam, which expects awareness of AppSync alongside API Gateway as ways to expose an API, and of when a GraphQL-shaped API might suit an application’s data needs. The Solutions Architect Associate expects the broader picture — recognising GraphQL as one architectural choice for how clients and services communicate, without needing implementation-level depth.
Original practice questions, timed mock exams and revision notes. No card, nothing to pay.