What Is GraphQL? A Query Language for Your API

GraphQL is a query language for APIs — and a runtime for executing those queries — where the client specifies exactly what data it needs and gets back precisely that, nothing more. Developed at Facebook in 2012 and open-sourced in 2015, it was built to solve the friction that large teams feel when a REST API doesn’t quite fit what the UI needs.

How GraphQL works

A GraphQL API exposes a single endpoint (commonly /graphql). Every request is a POST containing a query document — a structured description of the data the client wants. The server validates the query against a schema, resolves each field, and returns a JSON response that mirrors the shape of the request.

The schema is the core of GraphQL. It’s a typed contract between client and server that lists every type, every field, and every relationship the API can return. Both sides agree on this shape upfront, which makes the API self-documenting and enables powerful tooling.

Queries, mutations, and subscriptions

GraphQL has three root operation types:

• Query — read data (equivalent to GET in REST).
• Mutation — write or modify data (equivalent to POST/PUT/DELETE).
• Subscription — open a persistent connection and receive real-time updates as data changes.

Here’s a simple query asking for a user’s name and the titles of their blog posts:

query {
  user(id: "42") {
    name
    posts {
      title
    }
  }
}

The server returns exactly that structure:

{
  "data": {
    "user": {
      "name": "Ada Lovelace",
      "posts": [
        { "title": "Notes on the Analytical Engine" }
      ]
    }
  }
}

No extra fields, no missing fields.

Why GraphQL exists: over-fetching and under-fetching

These two problems are common with REST:

• Over-fetching — an endpoint returns more data than the client needs. A mobile app asking for a user’s name gets back the entire user object.
• Under-fetching — one endpoint doesn’t have everything you need, so you make multiple requests to different endpoints and stitch the results together yourself.

GraphQL eliminates both. The client asks for exactly the fields it needs in one round trip, even if those fields span multiple underlying data sources. This is especially valuable for mobile clients where bandwidth and latency matter.

GraphQL vs REST

	REST	GraphQL
Endpoints	Many (one per resource)	One
Data shape	Fixed by the server	Defined by the client
Over/under-fetching	Common	Eliminated by design
Caching	HTTP cache works out of the box	Requires explicit cache strategy
Learning curve	Gentle	Steeper (schema, resolvers, tooling)

REST is a perfectly good choice for simple, stable APIs — its HTTP-native caching and simplicity are real advantages. GraphQL pays off when you have multiple clients (web, mobile, third-party) with different data needs, or when the number of REST endpoints becomes hard to manage.

See our overview of what a REST API is and the broader concept of what an API is for context.

Tradeoffs to know before adopting GraphQL

Caching is harder. REST APIs can be cached at the HTTP layer with no extra work because each URL maps to a resource. GraphQL’s single endpoint and POST-based queries bypass standard HTTP caching; you need client-side caching tools like Apollo Client or a server-side persisted query strategy.

Query complexity can bite you. A naive GraphQL implementation lets clients write deeply nested queries that trigger expensive database joins. Production deployments add query depth limits, complexity analysis, or query whitelisting to prevent abuse.

The learning curve is real. Teams need to learn schemas, resolvers, and often a client library. The upfront cost is higher than standing up a simple REST route.

Takeaway

GraphQL is a powerful tool for APIs where clients have diverse, evolving data needs. Its typed schema, single endpoint, and client-driven queries eliminate a whole category of back-and-forth negotiation between teams. It’s not a replacement for REST in every situation, but for products with multiple clients or complex, interconnected data, GraphQL often becomes the more maintainable long-term choice.