Guides

GraphQL is a query language for APIs, and a runtime for answering those queries with your data. Created at Facebook in 2012 and released publicly in 2015, it gives the client — a web front end, a mobile app, or another service — a single, precise way to ask a server for exactly the data it needs, no more and no less. Instead of the server deciding the shape of every response, the client describes what it wants, and the server returns matching data in the same shape.

That single idea is what sets GraphQL apart from the REST style that preceded it. With REST you typically call several endpoints, each returning a fixed structure the server defined in advance. With GraphQL you send one request to one endpoint and specify the fields you want; the response mirrors your request. The aim is not to make REST obsolete but to solve specific problems that fixed endpoints create as an application and its data grow.

How GraphQL works: the schema

At the heart of GraphQL is the schema, a strongly typed contract that describes every type of data available and how those types relate. Because the schema is explicit and typed, both sides know in advance what is possible: tools can validate a query before it ever runs, editors can autocomplete fields, and documentation can be generated automatically from the schema itself. This self-describing nature is one of GraphQL's most practical advantages.

A GraphQL query reads almost like the JSON it returns. You name the fields you want, nest related fields inside them, and the server walks the schema to resolve each one. The same endpoint also accepts mutations, which change data, and subscriptions, which let the server push updates to the client over a persistent connection. Queries, mutations and subscriptions are the three operation types the specification defines.

Over-fetching and under-fetching

Two problems with fixed REST endpoints explain much of GraphQL's appeal: over-fetching and under-fetching. Over-fetching is when an endpoint returns far more data than a screen needs, wasting bandwidth. Under-fetching is the opposite — a single endpoint does not return enough, so the client must make several round trips to assemble one view. Because a GraphQL client asks for precisely the fields it needs in one request, it sidesteps both at once.

• Query language for APIs: the client asks for exactly the fields it needs
• Strongly typed schema = self-documenting, validated, autocompletable
• Three operations: queries (read), mutations (write), subscriptions (push)
• Solves REST's over-fetching and under-fetching in a single request
• Trade-offs: harder HTTP caching, query-cost safeguards; REST simpler for small APIs

GraphQL and front-end frameworks

This precision is especially valuable for front-end frameworks like React, Vue, Svelte and Angular, where a component often needs a specific slice of data. A component can request exactly the fields it renders, and as the interface evolves the query evolves with it, without waiting for a back-end team to build a new endpoint. Mature client libraries add caching, request batching and state management on top, which is why GraphQL became popular in component-driven front ends.

The honest trade-offs

GraphQL is not automatically the right choice, and being honest about its trade-offs matters. Its single dynamic endpoint makes the simple HTTP caching that REST enjoys harder, so caching usually moves into the client or a specialised layer. Carelessly written queries can ask for deeply nested data and strain the server, which is why production APIs add depth limits, cost analysis and other safeguards. For a small API with stable, predictable needs, REST is often simpler and perfectly sufficient.

What GraphQL is not

It is also worth being clear about what GraphQL is not. It is not a database or a storage engine — it sits in front of your existing data sources, whether those are databases, REST APIs or other services, and resolvers fetch from them. It is not tied to any single language or framework either; servers and clients exist across the whole ecosystem, and the specification is maintained by the vendor-neutral GraphQL Foundation rather than by one company.

GraphQL vs REST: how to choose

Choosing between GraphQL and REST comes down to your application's shape rather than fashion. GraphQL shines when many different clients need different slices of a complex, interconnected data graph, when front-end and back-end teams want to move independently, or when reducing round trips on slow connections is a priority. REST remains an excellent default for simpler services, public APIs that benefit from HTTP caching, and teams who value its ubiquity and simplicity.

Understood plainly, GraphQL is a way to let the client ask for exactly the data it wants, described by a typed schema, served from a single endpoint. It does not replace databases, REST or your existing services; it organises how clients talk to them. Knowing what problems it solves — and the caching and complexity costs it introduces — is what lets you reach for it when it genuinely fits, and leave it on the shelf when REST is the better tool.