GraphQL: Query Language for APIs

GraphQL: Asking for Exactly What You Need

Have you ever used an API that returned too much data, or not enough? That's the problem GraphQL was designed to solve. Instead of the server deciding what data to send, the client asks for exactly what it needs, and gets back only that. It's like ordering from a menu instead of getting a fixed set meal.

How GraphQL Works

At the heart of GraphQL is a schema — a description of all the data available and how it's connected. The schema is strongly typed, meaning every piece of data has a specific type: string, number, boolean, or more complex types like objects and lists. This schema acts as a contract between the client and server.

Clients send queries that describe exactly what they want. For example, a query might ask for a user's name and email, and the user's most recent orders. The server responds with a JSON object that matches the shape of the query — no extra data, no missing fields. This eliminates both over-fetching (getting data you don't need) and under-fetching (having to make multiple requests to get all the data you need).

Queries, Mutations, and Subscriptions

GraphQL has three types of operations. Queries are for reading data — they're the equivalent of GET requests. Mutations are for writing data — creating, updating, or deleting resources. Subscriptions are for real-time updates — the server pushes data to the client whenever something changes, like new notifications or live chat messages.

Resolvers: How Data Gets Fetched

On the server side, each field in the schema has a resolver function that knows how to fetch that data. Resolvers can call databases, external APIs, or compute values on the fly. They receive the parent object, arguments, a context (which typically contains authentication and database connections), and information about the query. GraphQL calls resolvers selectively — it only runs the resolvers for fields that were actually requested.

One common challenge is the N+1 problem, where fetching a list of items and then fetching a related field for each item results in many database queries. The solution is DataLoader, which batches and caches requests so that multiple resolvers that need the same data can share a single database query.

Federation: Combining Multiple Services

For large organizations, a single GraphQL schema can become unwieldy. Federation lets you split the schema across multiple services, each responsible for its own domain. A gateway combines them into a single unified graph that clients interact with. This enables independent teams to own their part of the API while presenting a cohesive experience to consumers.

GraphQL vs REST: When to Use Each

GraphQL excels when you have complex data relationships, multiple clients with different needs, and you want to iterate quickly without versioning. REST is simpler and more mature, with native caching, wider tooling support, and easier learning curve. For many projects, the best approach is to start with REST and move to GraphQL when the complexity justifies it.

GraphQL is not a replacement for REST — it's a different tool for different problems. Understanding both lets you choose the right one for each situation.