Most APIs work like a fixed menu. You call an endpoint, and the server decides what you get, even if you only wanted one small piece of it. GraphQL flips that around. It lets the client describe exactly what data it needs, and the server returns a response shaped just like the request. That one change is why so many teams adopted it for apps with complex, fast-changing screens.
Key Takeaways
GraphQL is a query language for APIs and a runtime for fulfilling those queries, built around a strongly typed schema.
Clients ask for exactly the fields they need in a single request, which avoids the over-fetching and under-fetching common in REST.
Three operation types cover most needs: queries read data, mutations change data, and subscriptions stream live updates.
The schema, written in Schema Definition Language, is the contract between client and server, and it makes an API self-documenting.
GraphQL is not a replacement for REST everywhere. Simple, stable, cache-friendly APIs are often better left as REST.
What GraphQL Actually Is
GraphQL defines itself as a query language for APIs and a server-side runtime for executing queries using a type system you define for your data. That definition has three parts worth unpacking. First, it is a language: clients write requests that name fields, not URLs. Second, it is a runtime: a server takes that request, runs it against its data sources, and returns matching data. Third, it is typed: every field has a declared type, so both sides agree in advance on what is possible.
GraphQL was created inside Facebook in 2012, when its mobile apps needed a more flexible way to fetch data than a growing pile of REST endpoints. Development of the open standard started in 2015, and the GraphQL Foundation was formed in 2019 as a neutral home for the ecosystem, according to the GraphQL specification. Today it is used by companies including GitHub and Shopify, whose public APIs are built on it.
The "graph" in the name describes how data is modelled. Instead of separate endpoints for users, posts, and comments, GraphQL presents one connected graph of types and fields. A client can start at a user, follow a field to that user's posts, and follow another field to each post's comments, all in a single request. The shape of the response mirrors the shape of the query, so there are no surprises about what comes back.
Queries: Ask for Exactly What You Need
A query is a read operation. It names the fields you want, and the server returns only those fields. Imagine a profile screen that needs a user's name, avatar, and the titles of their five latest posts. With REST, that might take two or three calls: one for the user, one for the posts, and possibly one more for related data. With GraphQL, one query can traverse those relationships and return the whole screen's data at once, as the official queries documentation explains.
This solves two classic REST problems. Over-fetching happens when an endpoint returns a full resource but the client only needs two fields, wasting bandwidth, especially on mobile connections. Under-fetching happens when one endpoint does not return enough, so the client must make extra round trips to fill in the gaps. GraphQL removes both by letting the client set the shape of each response.
Queries can also take arguments, such as an id or a limit, and they can be named and reused with variables. Two built-in directives, @include and @skip, let a client conditionally include or exclude a field based on a variable, which is handy for screens that change with user settings.
Mutations: Changing Data, Then Confirming It
If queries read data, mutations write it. A mutation creates, updates, or deletes records, and it returns the changed data in the same response, using the same field-selection syntax as a query. That last part matters in practice: after updating a post's title, the client can ask for the updated title, author, and timestamp in one round trip, instead of writing and then re-reading.
There is one important difference from queries. While query fields can resolve in parallel, mutation top-level fields run one after another, in sequence, as Hygraph notes. That ordering is deliberate: when two writes depend on each other, running them in order keeps the result predictable. Nested mutations can also change related entities in a single request, for example creating a post together with its first comment.
Subscriptions: Live Updates Without Polling
Queries and mutations follow a request and response pattern: the client asks, the server answers, and the connection closes. That pattern is a poor fit for live data such as chat messages, live scores, or online status, where the client would otherwise have to ask again and again to check for changes.
Subscriptions solve this with a publish and subscribe model, usually over WebSockets. The client opens one connection and subscribes to an event, and the server pushes an update whenever that event happens, without a new request per update, as Hygraph explains. A subscription uses the same operation style as queries and mutations, including variables, named operations, and fragments, so it feels like a natural third operation type rather than a separate system.
The Schema: The Contract That Documents Itself
Every GraphQL API is defined by a schema: a collection of types and fields that describes everything the server can do, written in Schema Definition Language (SDL). Apollo describes the schema as the full picture of what a GraphQL server can do, and that picture is also its documentation.
The schema defines three root operation types, Query, Mutation, and Subscription, plus the object types, fields, and relationships beneath them. The five built-in scalar types are Int, Float, String, Boolean, and ID, and types can be combined with list and non-null modifiers, enums, interfaces, and unions, according to Hygraph. For each field, the server runs a resolver function that fetches the value from a source such as a database or an existing REST API, which means GraphQL can sit on top of systems a team already has.
Because the schema is typed and queryable, tools can inspect it directly. This introspection is what powers autocomplete in editors like GraphiQL, automatic documentation, and code generation for clients. A developer joining a project can open the schema and see exactly what the API offers, without hunting through separate docs that may be out of date.
GraphQL vs REST: A Practical Comparison
GraphQL and REST solve the same problem in different ways, and the trade-offs are concrete rather than ideological. REST API Explained: How the Web's Most Common API Style Actually Works covers the REST side in detail. The table below sums up the main differences.
Aspect | REST | GraphQL |
|---|---|---|
Endpoints | One per resource, such as /users and /posts | Typically one, such as /graphql |
Response shape | Fixed by the server for each endpoint | Chosen by the client in each query |
Over-fetching | Common, endpoints return full resources | Avoided, only requested fields return |
Under-fetching | Common, related data needs extra calls | Avoided, nested data comes in one query |
Schema | Optional, often described with OpenAPI | Built in, strongly typed, self-documenting |
Versioning | Often needs /v1, /v2 endpoints | Evolves by adding fields and deprecating old ones |
Caching | Easy with HTTP caching and CDNs | Harder, needs client caches or persisted queries |
Learning curve | Low, familiar HTTP concepts | Higher, schema, resolvers, and tooling to learn |
REST still wins in several situations. When data comes from a single source and client needs are simple and stable, a REST API is easier to build, cache, and reason about, as Hygraph notes in its comparison. HTTP caching works out of the box for GET requests, which is a real advantage for public, read-heavy data. GraphQL, by contrast, usually sends requests as POST to a single endpoint, so standard HTTP caches cannot help as easily, and teams need client-side normalized caches or persisted queries instead.
GraphQL earns its complexity when requirements are complex and changing: many related resources on one screen, several client platforms with different data needs, or a frontend team that wants to move without waiting for new endpoints. It also brings risks to manage. Deeply nested queries can be expensive for a server, so production APIs need query depth limits, complexity limits, timeouts, and authentication checks on every field, not just at the endpoint level.
When to Choose Which
Choose GraphQL when a single screen pulls together many related resources, when mobile and web clients need different slices of the same data, or when the frontend changes faster than the backend can ship new endpoints. Choose REST when the API is simple, public and cache-friendly, or when the team is small and the cost of schema design, resolvers, and GraphQL tooling would outweigh the benefit. Many companies use both: REST for simple public endpoints, GraphQL for the complex product API behind their app.
Either way, the decision should follow the data, not the fashion. An API style is a tool, and the right one is the one that makes the actual screens your users see cheaper to build and safer to run.
Frequently Asked Questions
Is GraphQL a database?
No. GraphQL is a query language and runtime for APIs, not a database. Resolvers fetch data from whatever sits behind the API, which could be a database, another API, or a mix of both.
Does GraphQL replace REST completely?
No. REST remains a good fit for simple, stable, cache-friendly APIs. GraphQL is stronger for complex, related data and for clients with different data needs, but it adds server complexity that simple APIs do not need.
Do I need to learn a new language to use GraphQL?
You write queries in GraphQL's own query language, but it is small: fields, arguments, variables, and three operation types. Server code can be written in many languages, including JavaScript, Python, Ruby, Java, and Go.
Is GraphQL only for big companies?
No. Small teams can use it too, especially through managed or hosted GraphQL services. The question is whether your data needs justify the setup cost, not the size of your company.
How do I start learning GraphQL?
Start with the official documentation at graphql.org, then try a public GraphQL API, such as GitHub's, in an explorer tool. Writing a few queries against a real schema teaches more, faster, than reading about the syntax alone.