GraphQL: The Client Decides What to Fetch

GraphQL is a query language for APIs, developed at Facebook in 2012 and open-sourced in 2015, that flips the traditional power dynamic: the client tells the server exactly which fields it wants, and the server returns precisely that.

What it is

GraphQL is a query language plus a runtime for executing those queries against a schema. Instead of the server deciding the shape of every response, the client writes a query that selects exactly the fields it needs. The schema is a type system that acts as the shared contract between client and server, and it can generate documentation, client code, and query validation automatically.

Think of it as a buffet. You take exactly the dishes you want in the portions you need, rather than buying a fixed combo meal from REST and throwing away what you did not order.

Why it matters

• One query returns exactly the fields you need at the response layer, no over-fetch, no under-fetch.
• The schema type system generates docs and client code automatically, and supports introspection so clients can self-discover the API.
• GraphQL typically uses a single endpoint, like /graphql, instead of dozens of REST routes.
• It directly addresses the over-fetch and under-fetch problems that plague REST for clients with varying data needs.
• It is used in production at scale by Facebook, GitHub, Shopify, and Pinterest.

How it works

A client writes a query describing the data it needs for a specific screen. For example, a profile screen query might ask for a user's name, avatar URL, and the titles of their three most recent posts. The server returns a JSON object that mirrors the query tree exactly, with no extra fields like email, phone, or address, and no need for a second or third round trip.

GraphQL has three operation types. Query reads data. Mutation changes data. Subscription receives realtime pushes from the server. The schema declares types like User and Post with their fields and relationships, and resolvers are the common implementation pattern for fetching the data behind each field. The complexity of routing moves from many endpoints into the schema, query planning, and authorization layer.

Caveats

GraphQL solves over-fetch at the response level, but it does not automatically optimize backend data fetching. Resolvers can still trigger N+1 queries, so you need DataLoader or similar batching. HTTP caching is no longer automatic like REST GET requests, because queries are typically POST, so you need persisted queries or a normalized cache strategy. Rate limiting is harder because each query has a different cost, so you must meter by query complexity, not request count. And while the client does not receive extra fields, the server still has to optimize resolvers so the database is not over-queried.