GraphQL vs REST: A Practical Comparison for Production APIs in 2025

// REST over-fetching: client gets more than it needs
GET /users/123
// Returns: { id, name, email, phone, address, created_at, preferences, subscription, ... }
// Client only needed: { id, name }

// REST under-fetching: client needs multiple requests
// To show user profile with posts and followers:
GET /users/123          // 1 request
GET /users/123/posts    // 1 more request
GET /users/123/followers // 1 more request
// 3 round trips for one screen

// GraphQL: client specifies EXACTLY what it needs in ONE request
query UserProfile($id: ID!) {
  user(id: $id) {
    id
    name
    posts(last: 5) {
      title
      publishedAt
    }
    followers(first: 10) {
      name
      avatarUrl
    }
  }
}
// One request, exact fields, one round trip

// GraphQL introduces its own N+1 problem
// Resolving 100 posts, each needing author data:
query {
  posts {
    title
    author { name }  // Resolved separately for EACH post
  }
}
// Without optimization: 1 query for posts + 100 queries for authors = 101 DB calls!

// Fix: DataLoader — batch and cache resolver calls
const DataLoader = require('dataloader');

const userLoader = new DataLoader(async (userIds) => {
  // Batched: called ONCE with all IDs instead of once per post
  const users = await db.query('SELECT * FROM users WHERE id = ANY($1)', [userIds]);
  // Map results to match input order
  return userIds.map(id => users.find(u => u.id === id));
});

const resolvers = {
  Post: {
    author: (post) => userLoader.load(post.authorId)
    // DataLoader batches all authorId lookups: 1 DB query for 100 posts!
  }
};

// REST caching: simple, built into HTTP
GET /users/123 → Cache-Control: max-age=3600
// CDN, browser, proxy all cache automatically by URL

// GraphQL caching: harder — all queries go to same endpoint
POST /graphql  // POST = not cached by default
// Different queries = same URL = CDN can't differentiate

// GraphQL caching solutions:
// 1. Persisted Queries: hash query, GET with hash
GET /graphql?operationId=abc123hash
// Now cacheable by CDN!

// 2. Apollo Client: normalizes response into cache by entity + id
// user:123 cached separately from query result
// Subsequent queries that include user:123 fields served from cache

// 3. Field-level caching with cache hints
type User @cacheControl(maxAge: 3600) {
  id: ID!
  name: String!
  posts: [Post] @cacheControl(maxAge: 300) # Posts change more frequently
}