What is GraphQL? How it works and when you should use it

GraphQL is an open-source data query and manipulation language for APIs. Instead of calling many endpoints and receiving fixed response shapes, a client sends a query that describes exactly what data it wants, and the server returns precisely that data in the same shape. GraphQL is not tied to any particular database or storage engine, and several open-source runtimes implement it for different languages. This guide explains how GraphQL works, its core concepts of schema, queries, mutations and subscriptions, and how it compares to REST so you can decide when it is the right fit.

What problem does GraphQL solve?

Traditional REST and endpoint-based APIs have two common problems: over-fetching and under-fetching. Over-fetching happens when an endpoint returns a large fixed response and a client needs only a few fields — it downloads data it will never use. Under-fetching happens when a client needs data spread across several resources, so it has to make multiple round trips, one per endpoint, and then assemble the pieces.

GraphQL addresses both with a single endpoint and a declarative query. The client states the exact fields it needs, and the server resolves them from however many underlying data sources are required. The client gets one predictable response, shaped exactly like the query, with no more and no less than what it asked for.

A brief history

Facebook started developing GraphQL in 2012 and released a draft specification with a reference implementation as open source in 2015. In 2018 the project moved to the newly established GraphQL Foundation, hosted by the non-profit Linux Foundation. Since then many public APIs have adopted GraphQL, including those of GitHub, Shopify and Yelp. The specification is open, and the reference implementation GraphQL.js is MIT-licensed.

The schema and type system

A GraphQL service is built by defining a schema: the collection of types and fields that completely describes what the API can do. The schema uses a small type system that includes scalars (such as String, Int, Float, Boolean, and ID), object types, and a root Query type that lists everything that can be queried.

type Query {
  currentUser: User
}

type User {
  id: ID!
  name: String!
  email: String
  posts: [Post]
}

type Post {
  id: ID!
  title: String!
  published: Boolean!
}

A field is non-nullable when it ends with an exclamation mark, and a field can be defined as a list by wrapping its type in square brackets. The schema is the contract between client and server: the client can explore it and build queries that are guaranteed to match, and the server validates every request against it before execution.

Queries

A query defines the exact shape of the data the client needs. The server validates the query against the schema, executes it using functions called resolvers (one per field), and returns a result that mirrors the shape of the original query, typically as JSON.

query {
  currentUser {
    name
    email
  }
}

{
  "data": {
    "currentUser": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

Because the client selects the fields, adding a field to the query changes only the response, not the endpoint. There is no need to version the API or spin up a new endpoint when a client needs more data — it simply asks for it.

Mutations and subscriptions

GraphQL has three kinds of operations. Queries read data. Mutations modify data — creating, updating or deleting it — and they accept input variables and can return data matching the mutation's shape so the client gets the result of the change in one round trip.

mutation CreatePost($title: String!) {
  createPost(title: $title) {
    id
    title
    published
  }
}

Subscriptions push live updates from the server to the client. A client subscribes once and receives updates whenever the relevant data changes, commonly transported over WebSockets. Subscriptions are how GraphQL supports real-time features such as notifications and live dashboards.

How GraphQL works over HTTP

GraphQL is typically served over HTTP: a client sends a query, typically as POST to a single endpoint such as /graphql, and receives the result. The GraphQL specification is agnostic about transport, so the same query language can work over other transports such as WebSockets for subscriptions.

One key difference from REST is the single endpoint. A REST API usually exposes many URL endpoints, one per resource, and uses HTTP methods such as GET and POST. A GraphQL API exposes one endpoint and lets the body of the request describe the operation and the fields wanted. HTTP remains the underlying protocol, so the caching, status and header semantics defined in RFC 9110 still apply to the transport.

GraphQL vs REST

The two are not a strict either/or. GraphQL is often considered an alternative to REST, but it does not replace it — a GraphQL server can even sit in front of REST APIs, aggregating them behind a single schema, which is a common pattern for a microservice architecture acting as an API gateway.

REST shines when APIs are simple, stable and well-understood, and it benefits from mature caching across the web. GraphQL shines when clients have varied and evolving data needs — especially mobile clients and front-end applications with many views — and when you want one strongly typed contract that clients can explore.

When to use GraphQL

Use GraphQL when different clients need different fields of the same data, when a client-side view composes data from several sources in one round trip, or when you want a self-documenting, strongly typed API. It is also a strong fit as an API gateway in front of multiple services.

• Mobile + web parity: a small screen and a large screen rarely want the same fields; GraphQL lets each ask for exactly what it renders.
• Aggregation: one schema that combines data from several back-end services without the client making many calls.
• Rapid front-end evolution: adding fields usually means editing the query, not the server.

Skip GraphQL when your API is a small set of stable endpoints, when you rely heavily on HTTP caching of raw responses, or when a straightforward REST surface is enough — GraphQL adds conceptual and operational overhead (resolvers, caching strategy, tooling) that is only worth paying when the flexibility pays off.

Security considerations

GraphQL introduces a few concerns specific to its design. Because a single request can ask for nested data, you should protect the server against expensive or abusive queries:

• Query depth limits: cap how deeply a query can nest to stop recursive queries from exhausting resources.
• Query cost / complexity limits: estimate and cap the total work a query represents.
• Timeouts: bound how long the server spends executing a single operation.
• Introspection control: introspection, which lets clients explore the schema, can be disabled in production if you do not want to expose the full schema.
• Variables and batching: as with any API, validate input and protect against attacks such as injection and denial of service, and consider batching attacks where many queries are sent in one request.

Many of the security concerns with GraphQL are the same ones that apply to any API — authentication, authorization, input validation — handled in your business logic layer with common patterns such as JWTs or OAuth.

Conclusion

GraphQL is an open, transport-agnostic query language that gives clients precise control over the data they receive. Its explicit schema, strong typing and three operation types (queries, mutations, subscriptions) solve over-fetching and under-fetching, and its single-endpoint design exposes a self-documenting contract. Choose it when your clients have varied and evolving data needs, and keep REST when a simple, stable set of endpoints and mature HTTP caching are the better fit. For the request/response side of API design, see the REST API with Node.js and Express guide, and for how these endpoints connect across services, read what an API gateway is.

FAQ

What is GraphQL vs REST?

GraphQL is a query language where the client asks for exactly the fields it needs from a single endpoint. REST is an architectural style where each resource has its own URL endpoint and a fixed response shape. GraphQL avoids over-fetching and under-fetching by letting the client shape the response, while REST benefits from simpler URLs and mature HTTP caching. They can coexist — a GraphQL server can aggregate multiple REST APIs behind one schema.

Is GraphQL a database language like SQL?

No. GraphQL is a specification for remote client-server communication and is agnostic to the data source. Unlike SQL, it does not query a database directly. A GraphQL server coordinates resolver functions, which delegate to a business-logic layer that talks to whatever data sources you use — databases, other APIs or in-memory data.

Do I need a GraphQL client?

No, you can start by issuing GraphQL requests with a regular HTTP client. GraphQL clients such as Apollo and Relay add batching, caching, build-time schema validation and UI updates, and become valuable as your application grows, but they are optional.

How do I secure a GraphQL API?

Apply the same protections as any API — authentication, authorization, input validation — and add GraphQL-specific guards such as query depth limits, query cost limits, timeouts, and controlling introspection. Resolve authorization in your business-logic layer, and authenticate with standard patterns such as JWTs or OAuth.

Is GraphQL only for JavaScript or React?

No. GraphQL is a specification that can be implemented in any language, and many runtimes exist across the ecosystem. It was introduced at a React conference and the reference implementation is in JavaScript, which is why it is associated with that stack, but it is transport- and language-agnostic.

Verdict

GraphQL is a powerful, open query language that earns its place when clients have diverse and evolving data requirements and you want a single, strongly typed, self-documenting API contract. It solves real problems — over-fetching, under-fetching and multiple round trips — that grow more painful as front-ends and clients multiply. The trade-off is added complexity in resolvers and caching, so match the tool to the surface: reach for GraphQL when flexibility pays, and reach for REST when a simple, stable, cache-friendly API is all you need.