What is GraphQL?
Explore the origins, architecture, and core benefits of GraphQL. See how it solves REST's over-fetching and under-fetching problems.
Continue with the guided workspace
Use the paired workspace to connect this guide's mental model with live component state, visible signals, and the outcome each step or scenario is meant to prove.
GraphQL is an open-source data query and manipulation language for APIs, and a runtime for fulfilling queries with existing data. Developed internally by Meta (Facebook) in 2012 and open-sourced in 2015, GraphQL was designed to address the challenges of building mobile applications on slow cellular networks. Rather than forcing clients to adapt to rigid REST endpoints, GraphQL shifts control to the client, allowing it to request precisely the data it needs and nothing more.
Mental Model
Think of GraphQL like ordering a custom bento box at a restaurant, whereas REST is ordering a pre-set combo meal. Under REST (combo meal), if you order Combo A (user profile), you get a sandwich, a drink, and a side of chips, even if you only wanted the sandwich (over-fetching). If you also want a dessert, you must place a separate, second order (under-fetching). Under GraphQL (bento box), you hand the chef a list (query) showing exactly what you want: two sushi rolls, one slice of tempura, and no soup. The chef (GraphQL Gateway) goes to different food stations (User, Order, and Product databases), gathers exactly the items you requested, packages them into a single box (JSON payload), and hands it to you in one trip.
Components and Why They Exist
Client Application
The client application constructs specific queries and renders the returned JSON response. By declaring the exact fields and nested relationships required in a single query document, the client receives a response payload shaped precisely to that selection set.
GraphQL Gateway / Server
The GraphQL gateway centralizes endpoint logic, validates incoming queries against the schema, and orchestrates resolver functions before database calls. When a query arrives, the gateway parses the document, checks field types and depth limits, delegates child field lookups across resolvers concurrently, and stitches the final JSON response.
User Database
The user database stores profile attributes such as usernames, profile pictures, and contact details. Root user resolution requests scan this database for matching user rows and return only the profile columns selected by the query.
Order Microservice / Database
The order service manages purchase events, post or order lists, and customer history separately from user profiles. Nested query branches pull child records associated with the parent user IDs from this backing database tier.
Product Inventory Database
The inventory or comments store holds detailed child metadata associated with parent item IDs. Leaf resolvers fetch these child records—either naively per parent row or consolidated into a single batched lookup via DataLoader—to complete the nested response tree.
Edge Cases and Misconceptions
Over-fetching vs. Under-fetching
A common misconception is that GraphQL always performs better than REST because it reduces payload size. While GraphQL solves over-fetching at the network level between the client and gateway, it can transfer the problem to the backend. If the gateway’s resolver code naive-fetches entire records from databases and microservices only to filter out fields before returning them to the client, the database is still over-fetching.
Query Depth and DoS Attacks
Because GraphQL allows nested queries (e.g. user { friends { friends { friends } } }), a malicious client can write an infinitely nested query that recurses deeply. If processed, this query will exhaust the gateway’s CPU and memory, executing a Denial of Service (DoS) attack. Production GraphQL gateways prevent this by enforcing Query Depth Limits and calculating Query Complexity ratings before execution.
Schema Versioning
GraphQL is often advertised as requiring “no versioning” because fields can be deprecated rather than breaking the endpoint. However, if business logic changes fundamentally, keeping old fields alive can clutter resolver code and create database maintenance debt. Evolving a schema requires strict discipline, deprecating fields using @deprecated tags, and monitoring telemetry to see when old clients stop using them.
Common Questions
How does GraphQL solve the REST over-fetching problem?
In a REST API, endpoints return fixed data structures. If a client only needs a user's name, it might still download their address, bio, and settings. In GraphQL, the client defines the exact shape of the response in its query document, and the server returns only those requested fields, reducing payload size and network bandwidth.
How does GraphQL solve the REST under-fetching (N+1 database queries) problem?
Under-fetching occurs when a single REST endpoint doesn't provide enough data, requiring clients to make subsequent sequential requests (e.g. fetch `/user`, wait for ID, then fetch `/user/1/orders`, then loop to fetch `/products/X` for each order). GraphQL allows nesting queries to fetch related user, order, and product data in one client request, but it does not automatically remove backend N+1 database queries; resolver batching or a DataLoader-style utility is still required.
What is the N+1 Query Problem in GraphQL backends, and how is it resolved?
The N+1 problem occurs when resolving nested fields. For example, if a query requests 10 orders and their products, a naive resolver might execute 1 query to fetch the orders, and then 10 separate queries (one per order) to fetch the products. This is resolved using DataLoader, a utility that batches and debounces database requests, consolidating the 10 separate product queries into a single SQL `IN` query.
Why is caching harder in GraphQL compared to REST?
REST uses HTTP GET requests where the URL path uniquely identifies the resource, allowing standard web browsers, CDNs, and Varnish caches to cache responses at the network layer. GraphQL queries are typically sent as HTTP POST requests with identical URLs (e.g. `/graphql`) and varying request bodies, requiring application-level client caching (like Apollo Client cache) or specialized GraphQL CDN proxies.