GraphQL: Ask One Endpoint for Exactly the Fields You Need
Learn how GraphQL lets a client name the fields it wants, what it costs the server, and when REST is still the better choice.
In short
GraphQL lets a client ask one endpoint for exactly the fields it needs, at the cost of extra work on the server.
10 min readFree
What You Will Learn
This lesson explains GraphQL, a way for a client app to ask a server for exactly the data it shows. You will learn the main parts of GraphQL, the problems it solves, and the costs it brings. You will also see a worked example on a phone profile screen, and learn when a team should choose GraphQL instead of REST.
Read the key words first. The rest of the lesson uses them often.
Key words
- Client
- The app or web page that asks for data, such as a phone app.
- Server
- The computer program that receives requests and sends back answers.
- Endpoint
- One web address on a server where requests are sent.
- Type
- A named kind of data, such as User or Post, with a list of fields.
- Field
- One piece of data on a type, such as the name on a User.
- Schema
- The written list of types, fields, and requests that a GraphQL server accepts.
- Query
- A GraphQL request that reads data and does not change it.
- Mutation
- A GraphQL request that writes data, such as creating or changing a record.
- Resolver
- A server function that finds the value for one field.
- REST
- An older style of web API that uses many fixed addresses, one per resource.
- Round trip
- One request sent from the client and one reply received back.
- Over-fetching
- Getting more data than the screen needs.
- Under-fetching
- Getting too little in one call, so the client must ask again.
- Cache
- A stored copy of an answer, kept so the next request is faster.
- N+1 problem
- One list lookup followed by one extra lookup for each item in the list.
What Is GraphQL?
GraphQL is a query language and an execution engine for data in client-server apps. Its open standard is maintained as a published specification. The idea was first created in 2012, and the open standard work began in 2015.
In system design, GraphQL is one way that the parts of a system talk. It sits between clients and the data behind them. A client sends one request that lists the fields it wants. The server then returns data shaped like that request. REST is the main alternative, and the next sections compare the two.
What Is the Core Model?
GraphQL rests on three ideas: a typed schema, two kinds of request, and replies that follow the request's shape. Each idea is simple on its own. Together they explain why GraphQL behaves the way it does.
What Is the Typed Schema?
The schema is the contract between client and server. It lists the types the server knows, the fields on each type, and the requests a client may make. Every field has a type, such as text, a whole number, or a list of posts. The server checks each incoming request against the schema before it runs anything. The schema also serves as documentation. Adding a new field does not break old clients, because each client asks only for the fields it wants.
What Are Queries and Mutations?
Query for reads
A query asks for data. The client names the fields it wants, and the server returns them. Nothing on the server changes.
Mutation for writes
A mutation changes data, such as saving a new name. It also names the fields to return, so the client sees the result right away.
One endpoint for both
Both kinds of request usually go to one address, often a path named /graphql. The request body holds the text of the query or mutation.
Tip
A server does not have to offer mutations. Mutations are optional in the specification, so a read-only service can skip them.
Responses That Mirror the Query
The reply has the same shape as the request. If the query asks for a name inside a user, the reply holds a name inside a user. Fields the client did not ask for are left out. The short Python sample below shows the idea with plain dictionaries. It uses only the standard library.
user = {'id': 1, 'name': 'Ada', 'avatar': 'ada.png', 'bio': 'Writes about engines.', 'email': 'ada@example.com'}
wanted = ['name', 'avatar']
response = {'user': {field: user[field] for field in wanted}}
print(response)Output
{'user': {'name': 'Ada', 'avatar': 'ada.png'}}
What Problem Does It Solve?
Older REST APIs use many fixed addresses, one for each resource, such as one for a user and another for that user's posts. Each address returns a set of fields chosen by the server team. That fixed design causes two common problems.
Over-fetching and Under-fetching
Too much data
A fixed reply can carry many fields that the screen never shows. On a slow phone network, those extra bytes cost time and battery.
Too little data
A fixed reply can also hold too little. A profile screen may need one call for the user and a second call for the posts. Each call is a round trip.
The GraphQL change
The client lists the exact fields in one query. The server gathers related data and sends it back in one reply, so the app waits for fewer round trips.
The gain is largest on mobile networks, where each round trip can take a noticeable time. On a fast internal network between two servers, the gain is usually smaller.
Worked Example: A Profile Screen
A mobile social app shows a profile screen. The screen needs only three things: the user's name, the user's avatar picture, and the titles of the last three posts. We will compare the REST way with the GraphQL way.
- 1
Count the REST calls
REST needs a call to a user address, such as /users/1, for the name and avatar. It needs a second call to /users/1/posts for the posts. That is two round trips. The user reply may also carry fields the screen never shows, such as the bio and the email.
- 2
Write one GraphQL query
The app sends one query to the /graphql endpoint. The query lists only the fields the screen uses. The posts field takes a limit argument, which the schema defines.
- 3
Read the reply
The server runs the user lookup and the post lookup. It returns one reply shaped like the query: a user with a name, an avatar, and a list of three posts, each with a title. The bio and email are never sent.
- 4
Check the result
The app now makes one round trip instead of two. The reply holds only what the screen shows. The server still runs a post lookup for each user request, so it should batch that work, as the next section explains.
query ProfileScreen {
user(id: 1) {
name
avatar
posts(limit: 3) {
title
}
}
}The Trade-offs
GraphQL moves the hard work. With REST, the client makes many calls. With GraphQL, the server must answer one flexible query well. This brings three main costs.
Caching Is Harder
Web caches store copies of replies by their address. A CDN, which is a network of copy servers close to users, can store a REST reply for a fixed address. GraphQL usually sends each query as a POST request to one address. A POST asks the server to process data sent in the body, so simple address-based caches cannot store the reply. Teams often cache on the server or the client instead.
Persisted queries are one workaround. The client registers each query ahead of time and sends a short ID. The request then looks like a stable GET request that caches can store. The server also rejects queries it has never seen, which adds a security check.
The N+1 Problem
A naive server may run one lookup for a list of users, then one lookup for each user's posts. For 50 users, that is 51 backend calls. This is the N+1 problem. The first 1 is the list lookup, and N is the number of items. The cause is that each field's resolver runs on its own, without knowing what the other fields need.
The common fix is batching. A DataLoader is a helper that collects the keys requested during one request, runs one lookup for all of them, and reuses the results. With a DataLoader, the 50 post lookups become one lookup. Create a new DataLoader for each request, not one shared by all users, so one user's data never appears in another user's reply.
Expensive Queries
A client can nest fields deeply. It might ask for a user, then their posts, then each post's author, then that author's posts again. Each level can multiply the work. A short query text can therefore cost far more than it looks. A client that sends many such queries can overload a server, which slows it down for every other user.
Safeguards on the Server
Depth limit
The server rejects any query that nests deeper than a set number of levels.
Cost limit
The server estimates the work a query will cause and refuses queries above a set budget.
Batching resolvers
Helpers such as DataLoader group many small lookups so the database is called once per group.
Approved queries
The server runs only pre-approved, persisted queries, which also limits what clients can ask for.
Tip
A depth limit is a simple first step. A shallow query can still ask for a very large list, so pair it with a cost estimate and batching.
GraphQL or REST?
Neither style wins everywhere. Choose by looking at your clients and your data.
Choose GraphQL for varied clients
Use it when a phone app, a web page, and a partner each need a different view of the same data. It helps most when mobile networks make extra round trips costly.
Choose REST for simple, cacheable resources
Use it when data maps cleanly to resources and address-based caching matters most. REST also has broadly used tools and an easier learning curve.
Think twice for internal traffic
Between two services on a fast internal network, the gain from GraphQL is often small. Measure the real cost before you adopt it.
Tip
Choosing GraphQL does not remove the need for careful data access. The server still needs batching, limits, and a sound schema.
Check Your Understanding
Quick check
Your mobile app's home screen makes five REST calls and downloads large JSON objects, but it uses only a few fields, on a slow network. What change with GraphQL fits best, and what new server risk must you guard against?
Quick check
A government agency publishes read-only data about road works. Thousands of browsers fetch the same fixed pages every minute, and browsers cache by address. Which style fits best?
Summary
GraphQL lets a client ask one endpoint for exactly the fields it needs. The schema defines what can be asked. Queries read data, and mutations write it. The reply follows the shape of the query, which reduces over-fetching and under-fetching. The costs are harder caching, the N+1 problem, and expensive nested queries. Batching, depth limits, and cost limits keep the server safe. Use GraphQL for varied clients and REST for simple, cacheable resources.
Sources
- GraphQL Specification, working draft (spec.graphql.org)
- WunderGraph: Understanding the N+1 Problem in GraphQL
- ChilliCream HotChocolate docs: GraphQL DataLoader
- BeautifulCode: Solving GraphQL's N+1 Problem with DataLoader
- Encore: GraphQL vs REST
- Requestly: GraphQL vs REST, How to Choose and Test Both
- Postman blog: GraphQL vs REST, Choosing the Right API Architecture
- ArvuCore: GraphQL vs REST in 2026, When to Use Each API Style
- Apollo GraphQL Docs: Schema Basics
- Apollo GraphQL Tutorials: Introducing mutations
- DocsIO: GraphQL vs REST, A 2026 Pillar Guide
- Jitesh Prakash blog: GraphQL vs REST, Choosing the Right API Style
Last updated on 17 November 2026
Related lessons
Learn with me
Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.