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 interface that constructs specific queries and parses the JSON response. Drafts query files indicating the exact fields and nested relationships required, and submits them to the gateway. In the demo, observe the client designing a query schema and receiving a response conforming to that structure.
GraphQL Gateway / Server
Centralizes endpoint logic, executing resolver functions, and validating schemas before database calls. Parses the query document, validates it against the schema, invokes resolvers, and packages responses. In the demo, watch the gateway receive a query, validate it, and delegate child queries to resolvers concurrently.
User Database
Stores user profile attributes like username, profile picture, and demographic information. Returns user records matching the user IDs query requests generated by the parent resolver. In the demo, observe the database scanning for user rows to satisfy the gateway’s user resolution request.
Order Microservice / Database
Manages purchase events, billing details, and customer order history separately. Fetches transactions lists matching requested user ID keys, feeding the nested fields in the query. In the demo, observe order logs being pulled from the database node to satisfy user order query branches.
Product Inventory Database
Provides metadata about catalog items, such as descriptions, thumbnails, and price points. Supplies detailed product attributes associated with item IDs reference indices. In the demo, watch the product resolver pull catalog fields to fill out the leaves of the order 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.