system-design · intermediate

REST vs. GraphQL — Fixed Resources vs. Client-Driven Queries

The Central Question

Consider a mobile application running on the APILab platform (apilab.com):

• To render a user profile screen, the mobile app needs the user's name, avatarUrl, and the total count of unread notifications.
• Using a traditional REST API, calling GET /v1/users/4401 returns a heavy 15 KB JSON payload containing 45 un-needed fields (full address history, payment tokens, internal flags). This is Over-Fetching.
• Simultaneously, fetching unread notification counts requires a second HTTP call (GET /v1/notifications/unread), while fetching recent orders requires a third HTTP call (GET /v1/orders). This is Under-Fetching (Waterfalling).

GraphQL is an open-source query language and server-side runtime that allows clients to declare the exact data fields they require in a single HTTP request document, which the backend fulfills cleanly.

This lesson answers one central question: How do REST and GraphQL differ in client-server data fetching (over-fetching vs under-fetching), and how do engineers resolve GraphQL's primary operational hazard—the N+1 Database Query Problem—using DataLoader batching?

Over-Fetching vs. Under-Fetching (The REST Dilemma)

The architectural push for GraphQL stems from two inherent limitations of fixed-resource REST endpoints:

flowchart TD
  subgraph REST Dilemma
    OverFetch["1. Over-Fetching<br/>Client queries GET /v1/users/4401.<br/>Server returns 15 KB payload with 45 fields.<br/>Client uses only 2 fields! (Wasted Bandwidth)"]
    UnderFetch["2. Under-Fetching (Waterfalling)<br/>Client needs User + Orders + Notifications.<br/>Forces 3 sequential network round-trips!<br/>Latency = T1 + T2 + T3"]
  end
subgraph GraphQL Solution
    SingleQuery["Client sends 1 GraphQL Query Document to /graphql.<br/>Declares exact fields: user { name, avatar }, unreadCount.<br/>Server returns 1 trimmed JSON response in 1 round-trip!"]
  end
  
  OverFetch --> SingleQuery
  UnderFetch --> SingleQuery

Figure 1: Conceptual comparison of REST over-fetching / under-fetching vs GraphQL single-query execution.

1. Over-Fetching

2. Under-Fetching & Network Waterfalling

The GraphQL Mental Model: Single Endpoint & Schema SDL

Unlike REST, which exposes dozens of distinct URIs (/users, /orders, /products), GraphQL exposes a single HTTP endpoint (typically POST /graphql).

flowchart LR
  subgraph Client App
    Doc["GraphQL Query Document:<br/>query {<br/>  user(id: '4401') {<br/>    name<br/>    avatarUrl<br/>    unreadCount<br/>  }<br/>}"]
  end
  
  subgraph GraphQL Engine (POST /graphql)
    Schema[Schema SDL Definition] --> Parser[Query AST Parser & Validator]
    Parser --> Resolvers[Field Resolvers]
    Resolvers --> DB[(PostgreSQL / Redis)]
  end
  
  Doc -->|POST /graphql| Schema
  Resolvers -->|Exact JSON Response| Doc

Figure 2: The execution flow of a GraphQL query document against a single /graphql endpoint.

1. Schema Definition Language (SDL)

type User {
  id: ID!
  name: String!
  avatarUrl: String
  orders(limit: Int): [Order!]!
  unreadNotificationCount: Int!
}
type Order {
  id: ID!
  totalPrice: Float!
  status: String!
}
type Query {
  user(id: ID!): User
}

2. Client-Driven Selection Set

# Client Request sent to POST /graphql
query GetUserProfileScreen {
  user(id: "usr_4401") {
    name
    avatarUrl
    unreadNotificationCount
  }
}

3. Server JSON Response

{
  "data": {
    "user": {
      "name": "Alice Smith",
      "avatarUrl": "https://cdn.apilab.com/avatars/4401.jpg",
      "unreadNotificationCount": 3
    }
  }
}

The N+1 Database Query Problem

While GraphQL delivers unprecedented client flexibility, it introduces a severe backend performance hazard known as the N+1 Database Query Problem.

How the N+1 Bug Occurs

In a naive GraphQL implementation:

1. The root resolver executes 1 database query to fetch 100 order records (SELECT FROM orders LIMIT 100).
2. For each of the 100 orders, the GraphQL engine invokes the author field resolver individually.
3. The server executes 100 individual database queries (SELECT FROM users WHERE id = order.author_id).

sequenceDiagram
    autonumber
    participant Engine as GraphQL Engine
    participant DB as PostgreSQL DB
    
    Engine->>DB: 1. SELECT * FROM orders LIMIT 100 (Returns 100 Rows)
    DB-->>Engine: 100 Order Records
    
    loop 100 Times (The N+1 Disaster!)
        Engine->>DB: 2. SELECT * FROM users WHERE id = 1
        Engine->>DB: 3. SELECT * FROM users WHERE id = 2
        Engine->>DB: 4. SELECT * FROM users WHERE id = ...
        Engine->>DB: 101. SELECT * FROM users WHERE id = 100
    end

Figure 3: Sequence diagram detailing the N+1 query explosion during un-batched GraphQL resolution.

The Solution: DataLoader Batching & Caching

To solve the N+1 problem, production GraphQL servers use DataLoader batching.

DataLoader is a utility that collects individual load requests during a single event-loop tick, deduplicates keys, and executes a single batched SQL query using WHERE id IN (...):

sequenceDiagram
    autonumber
    participant Engine as GraphQL Engine
    participant DL as DataLoader Queue
    participant DB as PostgreSQL DB
    
    Engine->>DB: 1. SELECT * FROM orders LIMIT 100
    DB-->>Engine: 100 Order Records
    
    Note over Engine,DL: During 1 Event Loop Tick:<br/>100 author(id) calls queued into DataLoader!
    Engine->>DL: Queue Keys: [1, 2, 3, ... 100]
    
    DL->>DB: 2. ONLY 1 BATCH QUERY: SELECT * FROM users WHERE id IN (1, 2, 3, ... 100)
    DB-->>DL: Returns 100 User Rows
    DL-->>Engine: Maps User Rows back to 100 Resolvers!

Figure 4: DataLoader collapsing 100 individual user lookups into 1 batched SQL IN clause.

Using DataLoader, the query count drops from $1 + N$ ($101$ queries) down to 2 queries:

$$\text{Total DB Queries with DataLoader} = 1 + 1 = 2 \text{ Database Queries!}$$

Architectural Comparison Matrix

Schema Federation in Distributed Microservices

Complete Worked Example: Go GraphQL DataLoader Service

Let's inspect a complete Go implementation of a DataLoader batching resolver for the APILab platform (apilab.com) using dataloader.

package main
import (
	"context"
	"database/sql"
	"fmt"
	"strings"
"github.com/graph-gophers/dataloader/v7"
)
type User struct {
	ID   string
	Name string
}
type UserBatchLoader struct {
	db *sql.DB
}
func NewUserBatchLoader(db sql.DB) dataloader.Loader[string, User] {
	b := &UserBatchLoader{db: db}
	
	// Define the Batch Loading Function
	batchFn := func(ctx context.Context, keys []string) []dataloader.Result[User] {
		results := make([]dataloader.Result[User], len(keys))
		
		fmt.Printf("[DATALOADER BATCH] Collapsing %d user queries into 1 SQL IN clause!\n", len(keys))
		
		// Build SQL: SELECT id, name FROM users WHERE id IN ('1', '2', '3'...)
		placeholders := make([]string, len(keys))
		args := make([]interface{}, len(keys))
		for i, key := range keys {
			placeholders[i] = fmt.Sprintf("$%d", i+1)
			args[i] = key
		}
		
		query := fmt.Sprintf("SELECT id, name FROM users WHERE id IN (%s)", strings.Join(placeholders, ","))
		rows, err := b.db.QueryContext(ctx, query, args...)
		if err != nil {
			for i := range results {
				results[i] = &dataloader.Result[User]{Error: err}
			}
			return results
		}
		defer rows.Close()
userMap := make(map[string]*User)
		for rows.Next() {
			var u User
			rows.Scan(&u.ID, &u.Name)
			userMap[u.ID] = &u
		}
// Map results back to original keys order
		for i, key := range keys {
			if u, found := userMap[key]; found {
				results[i] = &dataloader.Result[User]{Data: u}
			} else {
				results[i] = &dataloader.Result[User]{Error: sql.ErrNoRows}
			}
		}
return results
	}
return dataloader.NewBatchedLoader(batchFn)
}

Failure Modes and Engineering Mitigations

What You Should Remember

1. GraphQL eliminates over-fetching and under-fetching: Clients request exact fields in a single POST document, avoiding heavy JSON payloads and sequential network waterfalls.
2. GraphQL uses a single endpoint: Rather than exposing dozens of REST URIs, GraphQL exposes POST /graphql backed by a strongly typed Schema SDL.
3. Always deploy DataLoader for N+1 queries: Without DataLoader batching, nested array queries execute $1 + N$ individual database lookups, crashing the primary database.
4. Enforce Max Query Depth limits: Protect GraphQL servers against Denial-of-Service attacks by restricting max query nesting depth and query complexity weights.
5. Use Persisted Queries for CDN caching: Convert HTTP POST query documents to GET hashes (/graphql?hash=...) to enable edge CDN caching for public read data.

Glossary of Terms

Practice Scenario and Self-Assessment

Architecture Scenario

• The feed displays 50 posts.
• Each post displays the author's name and avatarUrl, 3 top comments, and comment author names.

1. Formulate the REST endpoints required to render this screen, and explain the over-fetching and under-fetching trade-offs.
2. Write the GraphQL query document to fetch this screen in 1 network call, and calculate the total database queries required with vs without DataLoader batching.

Interactive Self-Assessment

The server fetches N parent items in 1 query, then executes N separate individual queries to resolve child relationships.

GraphQL disables database connection pooling over TCP sockets.

The JSON parser fails to decode nested object arrays in memory.

HTTP/1.1 limits database engines to processing 1 query per second.

It queues and deduplicates child lookup keys within an event loop tick, executing a single batched SQL 'WHERE id IN (...)' query.

It stores all database table records in client browser localStorage.

It converts GraphQL schemas into RESTful OpenAPI YAML specifications.

It encrypts database query strings using AES-256 encryption.

What to Learn Next

• REST vs RPC — Wire Protocol Trade-offs: Compare REST JSON vs gRPC Protobuf binary communication.
• API Gateway — Edge Entry for Microservices: Explore edge routing and BFF aggregation patterns.
• API Design — Clear Contracts Clients Can Trust: Revisit RESTful resource design conventions.

Track: Software Design and Architecture

Previous: Rate Limiter Design — Case Study

Next: REST vs. RPC — Wire Protocol and API Paradigm Trade-offs

By Shubham Jain

All articles · Study paths

Shubham Jain · Learning Lab