GraphQL vs REST — N+1 Query That Took Down a Product Page

Every modern app lives or dies by its API. Whether you're building a mobile app that has to load fast on a 3G connection in rural Brazil, or a dashboard that needs to stitch together data from five different services, the API architecture you choose on day one will haunt you — or reward you — for years. GraphQL and REST are the two dominant players in that space, and the choice between them is one of the most hotly debated decisions in backend engineering.

REST has been the industry standard for over two decades. It's predictable, HTTP-native, and every developer on earth has used it. But as UIs grew more complex and mobile clients became first-class citizens, REST started showing its cracks. Teams were hitting endpoints and getting mountains of data they didn't need, or worse, firing off six requests just to render a single screen. GraphQL was Facebook's answer to that pain, built internally in 2012 and open-sourced in 2015.

By the end of this article you'll be able to clearly explain the structural difference between REST and GraphQL, identify the specific scenarios where each one wins, spot the classic mistakes teams make when choosing between them, and walk into a system design interview with a confident, nuanced answer instead of a vague 'it depends.'

Why GraphQL and REST Are Not Interchangeable

GraphQL and REST are both API query paradigms, but they differ fundamentally in how they fetch data. REST exposes a set of endpoints, each returning a fixed structure. GraphQL exposes a single endpoint and lets the client specify exactly which fields it needs. This sounds like a minor difference, but it changes the entire data-fetching model from server-driven to client-driven.

In practice, REST works well when the client's data needs align with the server's predefined resources. GraphQL shines when clients have varied or nested data requirements — it eliminates over-fetching (getting 20 fields when you need 3) and under-fetching (needing multiple round trips to assemble a view). However, GraphQL shifts complexity to the server: a single query can trigger dozens of database calls if resolvers are naive, leading to the infamous N+1 problem.

Use REST when your API is simple, cache-friendly, and clients are predictable. Use GraphQL when you have multiple clients (web, mobile, IoT) with divergent needs, or when you need to aggregate data from multiple services. The choice isn't about which is 'better' — it's about which trade-offs your system can absorb.

How REST Actually Works — and Where It Starts to Break

REST (Representational State Transfer) organizes your API around resources. A resource is a noun — a User, an Order, a Product. You expose that resource at a URL, and HTTP verbs tell the server what to do with it: GET to read, POST to create, PUT/PATCH to update, DELETE to remove. This mapping is clean, intuitive, and stateless by design.

The trouble starts when your UI needs don't map neatly onto individual resources. Say you're building a Twitter-style profile page. You need the user's name and avatar, their last three tweets, and their follower count. In REST, that's three separate endpoints: GET /users/:id, GET /users/:id/tweets, GET /users/:id/followers. Three round trips. On mobile, each round trip is expensive.

The other side of that coin is overfetching. GET /users/:id might return 40 fields — date of birth, billing address, preferences, internal flags — when your profile page only needs four of them. You're downloading data you'll throw away, every single time.

These two problems — underfetching (too few fields, too many requests) and overfetching (too many fields, wasted bandwidth) — are not bugs in REST. They're structural consequences of organizing an API around fixed resource shapes instead of around what the client actually needs.

# Scenario: Render a user profile page using a typical REST API.
# We need: user name + avatar, their last 3 tweets, follower count.
# That means 3 separate HTTP requests.

# --- Request 1: Get the user's basic info ---
# Returns ~40 fields. We only need 'name' and 'avatar_url'.
curl https://api.example.com/users/42
# Response (truncated to show the overfetching problem):
# {
#   "id": 42,
#   "name": "Maya Patel",           <-- we need this
#   "avatar_url": "https://...",    <-- we need this
#   "email": "maya@example.com",    <-- not needed on this page
#   "date_of_birth": "1990-03-15",  <-- not needed on this page
#   "billing_address": {...},        <-- definitely not needed
#   "account_flags": [...],          <-- internal — should not even be here!
#   ... 34 more fields
# }

# --- Request 2: Get the user's recent tweets ---
# A separate round trip just to get 3 tweets.
curl https://api.example.com/users/42/tweets?limit=3
# Response:
# [ { "id": 101, "body": "...", "likes": 14 }, ... ]

# --- Request 3: Get follower count ---
# Yet another round trip for a single number.
curl https://api.example.com/users/42/followers/count
# Response:
# { \"follower_count\": 8321 }\n\n# TOTAL: 3 HTTP requests, ~40 wasted fields downloaded and discarded.\n# On a slow mobile connection, these requests are sequential or require\n# client-side orchestration to run in parallel \u2014 adding code complexity.",
        "output": "3 HTTP round trips fired to render one screen.\nResponse body for /users/42 is ~2.1 KB. Actual data used: ~180 bytes.\nOverfetch ratio: ~11x more data downloaded than needed."
      }

How GraphQL Solves Overfetching — and the Trade-offs It Introduces

GraphQL flips the model on its head. Instead of the server deciding what data a response contains, the client declares exactly what it needs in a query. The server exposes a single endpoint (typically POST /graphql) and a typed schema that describes every piece of data available. The client sends a query document describing the shape it wants, and the server returns exactly that shape — nothing more, nothing less.

That same profile page that needed three REST requests? One GraphQL query handles it. The client asks for user name, avatar, their last three tweets, and follower count in a single request. The server resolves all of it and returns one response shaped exactly like the query.

But GraphQL isn't a free lunch. That flexibility comes with real costs. Caching gets harder — REST leverages HTTP caching at the URL level natively, while GraphQL's single endpoint makes URL-based caching useless by default (you need tools like Apollo Client's normalized cache or persisted queries). Query complexity is another concern: a malicious or poorly-written client can craft a deeply nested query that brings your database to its knees. You need query depth limiting and complexity analysis in production. The learning curve for schema design and resolvers is also steeper than standing up REST routes.

# The same profile page data — now in a single GraphQL query.
# The client is 100% in control of the shape of the response.

query GetUserProfile($userId: ID!, $tweetLimit: Int!) {\n  # Fetch the user by ID\n  user(id: $userId) {\n    # Ask for ONLY the fields this page actually renders\n    name\n    avatarUrl\n\n    # Nested query for tweets \u2014 limit is passed as a variable\n    tweets(limit: $tweetLimit) {\n      id\n      body\n      likeCount\n    }

    # A computed field on the User type — resolved server-side
    followerCount
  }
}

# Variables sent alongside the query (not hardcoded in the query string)
# {
#   "userId": "42",
#   "tweetLimit": 3
# }

# --- What the server returns ---
# {\n#   \"data\": {\n#     \"user\": {\n#       \"name\": \"Maya Patel\",\n#       \"avatarUrl\": \"https://cdn.example.com/avatars/42.jpg\",\n#       \"tweets\": [\n#         { \"id\": \"101\", \"body\": \"Just shipped a new feature!\", \"likeCount\": 14 },\n#         { \"id\": \"98\",  \"body\": \"GraphQL resolvers are wild.\",  \"likeCount\": 31 },\n#         { \"id\": \"95\",  \"body\": \"Coffee > sleep.\",              \"likeCount\": 7  }\n#       ],\n#       \"followerCount\": 8321\n#     }\n#   }\n# }\n\n# TOTAL: 1 HTTP request. Response contains EXACTLY the fields requested.\n# Response body: ~310 bytes. Zero wasted data.",
        "output": "1 HTTP request fires.\nResponse body: ~310 bytes \u2014 matches exactly what the UI needs.\nNo overfetching. No underfetching. No client-side orchestration needed."
      }

Real-World Decision Framework — When to Actually Pick Each One

The honest answer isn't 'GraphQL is better' or 'REST is simpler.' The right answer depends on the shape of your problem. Here's how senior engineers actually think about this decision.

Choose REST when your data model is simple and resource-oriented, your clients are few and controlled (e.g., internal services talking to each other), you need aggressive HTTP caching (CDN caching of GET endpoints is trivially easy with REST), or your team is small and you want zero-overhead tooling. Public APIs that third-party developers will consume are also often better served by REST — it's more universally understood and doesn't require GraphQL client libraries.

Choose GraphQL when you have multiple client types with different data needs — a mobile app, a web app, and a third-party integration all hitting the same backend. It's the perfect fit for a BFF (Backend for Frontend) layer. Also choose it when your product is iteration-heavy: adding a new field to a GraphQL schema is non-breaking by default, whereas adding a new REST endpoint requires versioning discussions. Rapid product teams love this.

The hybrid approach is increasingly common: REST for simple CRUD microservices talking to each other, GraphQL at the edge as an API gateway that stitches them together for clients. This is the architecture used by major platforms like GitHub (which offers both APIs) and Shopify.

// A minimal but production-aware GraphQL server using Apollo Server.
// Demonstrates: schema definition, resolvers, and the depth-limiting
// protection you MUST add before going to production.

const { ApolloServer, gql } = require('apollo-server');
const depthLimit = require('graphql-depth-limit'); // npm install graphql-depth-limit

// --- Step 1: Define the Schema ---
// The schema is a contract between server and client.
// Every field, type, and relationship is declared here.
const typeDefs = gql`
  type Tweet {\n    id: ID!\n    body: String!\n    likeCount: Int!\n  }

  type User {
    id: ID!
    name: String!
    avatarUrl: String!
    followerCount: Int!
    # The 'limit' argument lets the client control how many tweets to fetch
    tweets(limit: Int = 10): [Tweet!]!
  }

  type Query {
    user(id: ID!): User
  }
`;

// --- Step 2: Mock data (replace with DB calls in production) ---
const USERS = {
  '42': {
    id: '42',
    name: 'Maya Patel',
    avatarUrl: 'https://cdn.example.com/avatars/42.jpg',
    followerCount: 8321,
  },
};

const TWEETS_BY_USER = {\n  '42': [\n    { id: '101', body: 'Just shipped a new feature!', likeCount: 14 },
    { id: '98',  body: 'GraphQL resolvers are wild.',  likeCount: 31 },
    { id: '95',  body: 'Coffee > sleep.',              likeCount: 7  },
    { id: '91',  body: 'Depth limits save lives.',     likeCount: 22 },
  ],
};

// --- Step 3: Resolvers ---
// Each resolver is a function that returns data for one field in the schema.
// Apollo walks the query tree and calls the right resolver for each field.
const resolvers = {\n  Query: {\n    // Called when client queries: user(id: \"42\") { ... }\n    user: (parent, args) => {\n      const foundUser = USERS[args.id];\n      if (!foundUser) throw new Error(`User ${args.id} not found`);\n      return foundUser;\n    },\n  },\n  User: {\n    // Called for each User object to resolve its 'tweets' field\n    // 'parent' is the User object returned by the Query.user resolver\n    tweets: (parent, args) => {\n      const allTweets = TWEETS_BY_USER[parent.id] || [];\n      // Respect the 'limit' argument the client passed in\n      return allTweets.slice(0, args.limit);\n    },\n  },\n};\n\n// --- Step 4: Server with depth limiting ---\n// Without this, a client could send a query like:\n// { user { followers { following { tweets { author { followers { ... } } } } } } }\n// ...and recursively query until your DB cries.\nconst server = new ApolloServer({\n  typeDefs,\n  resolvers,\n  validationRules: [\n    depthLimit(5), // Reject any query nested deeper than 5 levels\n  ],\n});\n\nserver.listen({ port: 4000 }).then(({ url }) => {\n  console.log(`GraphQL API ready at ${url}`);\n});",
        "output": "GraphQL API ready at http://localhost:4000/\n\n# Send this query via curl or Apollo Sandbox:\n# query { user(id: \"42\") { name avatarUrl followerCount tweets(limit: 3) { body likeCount } } }\n#\n# Response:\n# {\n#   \"data\": {\n#     \"user\": {\n#       \"name\": \"Maya Patel\",\n#       \"avatarUrl\": \"https://cdn.example.com/avatars/42.jpg\",\n#       \"followerCount\": 8321,\n#       \"tweets\": [\n#         { \"body\": \"Just shipped a new feature!\", \"likeCount\": 14 },\n#         { \"body\": \"GraphQL resolvers are wild.\",  \"likeCount\": 31 },\n#         { \"body\": \"Coffee > sleep.\",              \"likeCount\": 7  }\n#       ]\n#     }\n#   }\n# }"
      }

The Hybrid Architecture — GraphQL Gateway + REST Microservices

You don't have to pick one. The most mature production architectures use both: REST between internal microservices and GraphQL at the edge. Here's why that pattern wins.

Internal services talk to each other over REST (or gRPC). These calls are simple, cacheable at the service proxy level, and don't benefit from GraphQL's flexibility because each service has exactly one consumer. Adding GraphQL between internal services adds schema overhead and latency with no payoff.

At the edge, a GraphQL gateway sits between your clients and your internal services. The gateway resolves queries by making REST calls to the backend services. Clients get the benefits of GraphQL — declarative data fetching, reduced overfetching, single round trip — while your internal architecture stays simple and decoupled.

This pattern is what GitHub, Shopify, and Netflix run in production. GitHub's v4 GraphQL API is a gateway that aggregates data from over 200 internal REST services. Clients never know. They just send a query and get back exactly what they need.

// Example: GraphQL resolver that calls a REST microservice.
// The gateway doesn't talk to databases directly — it aggregates REST APIs.

const { ApolloServer, gql } = require('apollo-server');
const axios = require('axios');

const typeDefs = gql`
  type Product {
    id: ID!
    name: String!
    price: Float!
    # This field comes from a different microservice
    stockLevel: Int
  }

  type Query {
    product(id: ID!): Product
  }
`;

const resolvers = {
  Query: {
    product: async (_, { id }) => {
      // Call the internal Product REST API
      const { data } = await axios.get(`http://product-service:3000/api/products/${id}`);
      return data;
    },
  },
  Product: {\n    stockLevel: async (parent) => {\n      // Separate call to Inventory microservice\n      const { data } = await axios.get(`http://inventory-service:3001/api/stock/${parent.id}`);
      return data.quantity;
    },
  },
};

const server = new ApolloServer({ typeDefs, resolvers });
server.listen(4000).then(() => console.log('Gateway ready'));

Production Considerations — Caching, Security, Monitoring

Both REST and GraphQL have production pitfalls that you won't find in tutorials. Here's what actually matters when your API is handling millions of requests.

Caching is the biggest practical difference. REST endpoints are trivially cacheable at the CDN layer because each URL is unique. CDNs can cache GET /users/42 for 300 seconds and serve the cached copy to the next thousand requests. GraphQL's single endpoint means every request is a POST with a different query body — CDN caching is useless unless you use persisted queries (where each query has a unique hash ID). If your team cares about CDN cache hit rates, REST wins hands down.

Security: REST benefits from the full HTTP security toolkit — rate limiting by URL, WAF rules per path, IP allowlisting per resource. GraphQL requires you to implement depth limiting, query cost analysis, and allowlisting of known operations. Without these, a single malicious query can DDoS your entire API.

Monitoring: REST’s HTTP status codes map cleanly to error budgets and alerting — 5xx rate goes up, pager goes off. GraphQL returns 200 even for partial failures, so your monitoring must parse response bodies for errors. Most teams miss this and only realize after an incident that their error rate looked fine while users were seeing partial data.

Neither architecture is more secure or more observable by nature — they just require different tooling. The team that plans for these differences will sleep better at night.

// Middleware to alert on GraphQL errors that return HTTP 200.
// Without this, your monitoring won't detect partial failures.

app.use('/graphql', (req, res, next) => {
  const originalJson = res.json.bind(res);
  res.json = function (body) {
    if (body && body.errors && body.errors.length > 0) {
      // Log all errors
      console.error('[GraphQL Error]', JSON.stringify(body.errors));
      
      // Trigger alert if there are any non-client errors
      const serverErrors = body.errors.filter(e => e.extensions?.code !== 'BAD_USER_INPUT');
      if (serverErrors.length > 0) {
        // Send to PagerDuty / Opsgenie
        metricClient.increment('graphql.server_error', serverErrors.length);
      }
    }
    return originalJson(body);
  };
  next();
});

The Schema Contract: Why Your Code Editor Becomes Your Best Debugger

REST APIs are basically a gentleman's agreement. You hope the docs are accurate, you pray the endpoint returns what you expect, and you lose a Friday afternoon tracing a missing field. GraphQL forces honesty through a strongly typed schema. That schema isn't just documentation — it's the source of truth your client and server both compile against. When we shipped a GraphQL gateway over twenty REST microservices, the schema caught three data shape mismatches before they hit production. The tooling matters more than you think. IDEs auto-complete queries. Linters reject invalid field requests at build time. You shift failure from runtime to compile time. That changes your entire deployment cadence. The trade-off? Schema design requires upfront discipline. REST lets you throw endpoints together. GraphQL demands you define your data graph before you write resolvers. Most teams underestimate that cost until they're rewriting schemas in month two.

// io.thecodeforge
// Schema-first approach catches missing fields at compile time
import { ApolloError } from 'apollo-server-express';

// This resolver fails at build if orderQuery returns wrong shape
const orderResolver = {
  Query: {
    order: async (_, { id }, { dataSources }) => {
      const raw = await dataSources.orderAPI.fetchById(id);
      // Schema type: Order { id, status, total, items[] }
      // If raw.total is undefined, we crash fast instead of silently null
      if (!raw || !raw.id) {
        throw new ApolloError('Order not found', 'ORDER_NOT_FOUND');
      }
      return {
        id: raw.id,
        status: raw.status || 'UNKNOWN',
        total: parseFloat(raw.total || '0'),
        items: raw.items ? raw.items.map(mapItem) : [],
      };
    },
  },
};

export default orderResolver;

Overfetching Is the Symptom — The Real Disease Is N+1 Queries in GraphQL

Everyone loves to hate REST for overfetching. Fair. But GraphQL introduces a nastier problem: N+1 queries. Your client requests a list of orders, each with line items. One query becomes one-plus-N database calls. Your response time explodes from 50ms to 2 seconds. REST does this too with nested resources, but at least REST forces you to think about endpoints. GraphQL's flexibility makes it too easy to write an innocent-looking query that murders your database. We fixed this with DataLoader — batching and caching per request. But here's the thing: you don't know you have an N+1 problem until it hits production under load. REST's endpoint-per-resource pattern limits the blast radius. GraphQL's single endpoint means one bad query takes down everything. You need query cost analysis, depth limiting, and pagination enforcement. Otherwise, your users trigger an accidental DDoS every time they refresh a dashboard.

// io.thecodeforge
// DataLoader batches N+1 queries into one SQL IN clause
import DataLoader from 'dataloader';
import db from '../db/pool';

// Without this: N queries for line items
// With this: 1 query for all line items
const batchLineItems = async (orderIds) => {
  const result = await db.query(
    `SELECT * FROM line_items WHERE order_id = ANY($1)`,
    [orderIds]
  );
  // Group by order_id to return arrays per key
  const grouped = {};
  result.rows.forEach(row => {
    if (!grouped[row.order_id]) grouped[row.order_id] = [];
    grouped[row.order_id].push(row);
  });
  return orderIds.map(id => grouped[id] || []);
};

export const createLoaders = () => ({
  lineItemLoader: new DataLoader(batchLineItems),
});

// In resolver: return context.loaders.lineItemLoader.load(parent.id);