paulserban.eu

Writing Edition

Paul Serban

Writing, snippets & book notes

Vol. 2026

April 5, 2020

REST API vs GraphQL: Choosing the Right API Design for Your Application

A practical engineering comparison to help you pick the right data-access architecture

Introduction

Every application that talks to a server has to answer the same basic question: how should the client ask for data, and how should the server respond? That question sounds simple, but the answer shapes almost everything downstream - how your frontend teams write queries, how your backend scales, how you version your contracts, and how much bandwidth your mobile users burn through on a slow connection. Two architectural approaches dominate this decision today: REST (Representational State Transfer) and GraphQL.

This post is not a popularity contest between the two. Both are mature, production-proven approaches used at massive scale, and neither is objectively "better" in the abstract. Instead, we'll look at what each one actually optimizes for, where the tradeoffs bite in real systems, and how to make a defensible architectural decision rather than a fashion-driven one.

Context: The API Design Problem

APIs exist to let independently deployed systems exchange data and functionality without knowing about each other's internals. That sounds abstract until you consider what happens without a stable contract: a mobile app update breaks because the backend renamed a field, a partner integration silently returns malformed data because an endpoint changed shape, or a frontend team ships a slow screen because a single view requires stitching together six different network calls. Good API design is fundamentally about managing this coupling between client and server in a way that both sides can evolve safely.

The tension that both REST and GraphQL are trying to resolve is between server-defined contracts and client-defined needs. A server team wants predictable, cacheable, well-documented endpoints they can reason about and secure. A client team wants exactly the data a given screen or feature needs - no more, no less - delivered in as few round trips as possible. When these two goals align, the API design choice barely matters. When they diverge - as they inevitably do in large or fast-moving products - the architecture you picked either absorbs the friction gracefully or turns into a constant source of technical debt.

Historically, REST became the default because HTTP already gave engineers most of what they needed: verbs, status codes, caching semantics, and a mental model borrowed directly from the web itself. GraphQL emerged later, in large part because Facebook's mobile teams ran into the over-fetching and under-fetching problems described above at a scale where they became genuinely expensive. Understanding that origin story matters, because it explains why GraphQL's design choices center so heavily on flexible querying rather than, say, caching or simplicity.

REST API: Architecture and Principles

REST was formalized by Roy Fielding in his 2000 doctoral dissertation, "Architectural Styles and the Design of Network-based Software Architectures," where he described a set of architectural constraints for building scalable, loosely coupled distributed systems. In practice, a RESTful API exposes resources - users, orders, products - as URLs, and lets clients act on those resources using standard HTTP methods: GET to read, POST to create, PUT or PATCH to update, and DELETE to remove. This mapping between HTTP semantics and CRUD operations is what gives REST its familiarity; almost any engineer who has used the web already has the right mental model.

REST's defining architectural constraints are worth naming explicitly because they explain its strengths. It is stateless, meaning every request carries all the context the server needs to process it, with no reliance on server-side session state between calls. It is cacheable, since HTTP already defines rich caching semantics (ETag, Cache-Control, Last-Modified) that CDNs, browsers, and proxies understand natively. And it is layered, meaning a client doesn't need to know whether it's talking directly to an origin server or through a chain of intermediaries like load balancers or gateways. These constraints are precisely why REST scales so well on the open web: infrastructure built for HTTP - reverse proxies, CDNs, API gateways - works with RESTful APIs out of the box.

GraphQL: Architecture and Principles

GraphQL was developed internally at Facebook starting in 2012 to address exactly the mismatch described in the previous section: mobile clients pulling in bloated REST responses full of fields they didn't need, or having to make several chained requests to assemble a single screen. Facebook open-sourced the specification in 2015, and it's now maintained by the GraphQL Foundation under the Linux Foundation. Unlike REST, GraphQL is not tied to HTTP verbs or resource URLs; it's a query language and a runtime for executing those queries against a schema you define.

The core idea is that the client describes the exact shape of the data it wants, and the server returns precisely that shape - nothing more. A single GraphQL request can traverse relationships that would otherwise require several REST calls: fetching a user, their recent posts, and each post's comment count, all in one round trip. This is enabled by GraphQL's strong type system: every field, argument, and relationship is declared in a schema written in the GraphQL Schema Definition Language (SDL), which the server validates queries against before execution.

The third defining feature is introspection. Because the schema is itself queryable, tools like GraphiQL, Apollo Studio, and GraphQL Playground can generate interactive documentation, autocomplete, and type-checked queries automatically, without a developer maintaining separate API docs by hand. This tooling ecosystem is one of the more underrated reasons teams adopt GraphQL - the schema becomes a living, enforceable contract rather than a Markdown file that quietly goes stale.

Deep Technical Comparison

The clearest way to compare these architectures is along the specific dimensions where their design philosophies actually diverge. Data retrieval is the most fundamental one: REST's response shape is fixed per endpoint, decided by the server ahead of time. If a mobile client needs only a user's name and avatar but the /users/:id endpoint returns twenty fields, that's over-fetching. If the client also needs the user's last three orders and that requires a second call to /users/:id/orders, that's under-fetching resolved through additional round trips. GraphQL collapses both problems by letting the client specify the exact fields and nested relationships it wants in a single query.

Endpoint design is the second major divergence. A REST API for a moderately complex domain typically grows dozens or hundreds of endpoints as it matures - one or more per resource, often with variants for filtering, pagination, and nested resources. GraphQL, by contrast, exposes a single endpoint (conventionally /graphql) that accepts queries and mutations describing the requested operation. This has real consequences for versioning: instead of introducing /v2/users, teams typically evolve a GraphQL schema by adding new fields and deprecating old ones in place, since clients only ask for the fields they actually use.

Error handling differs in a way that's easy to underestimate until you've debugged a production incident. REST APIs communicate failure primarily through HTTP status codes - 404 for not found, 400 for bad input, 500 for server errors - which is a coarse-grained vocabulary that often needs a custom error body to convey anything specific. GraphQL, because every request technically returns 200 OK at the transport level (it's still an HTTP response under the hood), reports errors inside the response payload itself, alongside whatever partial data was successfully resolved. This lets a single response say "here's the user's profile, but their orders failed to load, and here's exactly why" - something REST can't express in one call without custom conventions.

Real-time updates round out the comparison. REST has no native mechanism for pushing changes to a client; teams typically bolt on polling (repeatedly re-fetching an endpoint) or a separate protocol like WebSockets or Server-Sent Events. GraphQL defines subscriptions as a first-class operation type in its specification, typically implemented over WebSockets, letting clients declare "notify me when this data changes" using the same query language they use for reads and writes.

Implementation: Practical Examples

Seeing the difference in actual code makes the architectural tradeoffs concrete. Below is a realistic REST implementation using Express.js, exposing a users resource with a nested orders relationship that requires a second endpoint to fetch:

// REST API - Express.js
import express from "express";
import { getUserById, getOrdersByUserId } from "./db";

const app = express();

// Fetch a user by ID - returns the full user record
app.get("/users/:id", async (req, res) => {
  const user = await getUserById(req.params.id);
  if (!user) {
    return res.status(404).json({ error: "User not found" });
  }
  res.status(200).json(user);
});

// Fetching a user's orders requires a second round trip
app.get("/users/:id/orders", async (req, res) => {
  const orders = await getOrdersByUserId(req.params.id);
  res.status(200).json(orders);
});

app.listen(3000);

A client that needs a user's name alongside their three most recent order totals has to make two HTTP calls and then merge the results client-side - and it still receives every field on the user object, whether or not the UI uses them.

Here's the equivalent modeled in GraphQL, using Apollo Server. The schema declares the relationship directly, and a single query resolves both the user and their orders in one round trip:

// GraphQL API - Apollo Server
import { ApolloServer } from "@apollo/server";
import { startStandaloneServer } from "@apollo/server/standalone";
import { getUserById, getOrdersByUserId } from "./db";

const typeDefs = `#graphql
  type Order {
    id: ID!
    total: Float!
    createdAt: String!
  }

  type User {
    id: ID!
    name: String!
    email: String!
    orders(limit: Int): [Order!]!
  }

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

const resolvers = {
  Query: {
    user: (_parent: unknown, args: { id: string }) => getUserById(args.id),
  },
  User: {
    orders: (parent: { id: string }, args: { limit?: number }) =>
      getOrdersByUserId(parent.id, args.limit),
  },
};

const server = new ApolloServer({ typeDefs, resolvers });
await startStandaloneServer(server, { listen: { port: 4000 } });

A client can now ask for exactly what it needs in a single request:

query GetUserWithRecentOrders {
  user(id: "42") {
    name
    orders(limit: 3) {
      total
      createdAt
    }
  }
}

Notice what's absent from the response: the user's email, and any order fields beyond total and createdAt. The client declared its needs, and the server's resolver layer - the orders function on the User type - handled fetching only what was requested, including the limit argument that constrains the nested collection.

Trade-offs and Pitfalls

Neither architecture is free of sharp edges, and the mistakes teams make usually come from underestimating the cost of the tradeoff they picked. REST's biggest practical pitfall is exactly the over-fetching and under-fetching problem discussed above - it doesn't show up as a crisis on day one, but it compounds as an application's screens grow more complex and a single view needs data from several resources. Teams often respond by growing ad hoc "aggregation" endpoints (/dashboard-summary) that exist purely to avoid multiple round trips, which works but slowly turns the API surface into a collection of screen-specific endpoints rather than clean resource models.

GraphQL's pitfalls are different but just as real. Because a single query can traverse arbitrarily deep relationships, a naive resolver implementation is vulnerable to the N+1 query problem: fetching a list of users and then, for each user, issuing a separate database query for their orders, resulting in dozens or hundreds of queries for one GraphQL request. This is typically solved with request-scoped batching tools like Facebook's own DataLoader library, but it's an extra piece of infrastructure REST doesn't require by default. GraphQL also complicates HTTP-level caching: since every request hits the same endpoint with a POST body, the CDN and browser caching that REST gets for free from HTTP semantics doesn't apply out of the box, and teams need persisted queries or client-side caching layers like Apollo Client's normalized cache to compensate.

Best Practices

Whichever architecture you choose, a handful of practices consistently separate healthy APIs from ones that become liabilities. For REST APIs, model your URLs around resources and their relationships rather than actions (/users/42/orders, not /getUserOrders?id=42), use HTTP status codes consistently and document deviations, and design for cache-friendliness from the start - GET requests should be idempotent and cacheable wherever the data allows it. Versioning strategy matters early: deciding between URL versioning (/v2/users), header-based versioning, or additive-only schema evolution should happen before your first breaking change forces the decision on you.

For GraphQL APIs, invest in batching and caching at the resolver layer immediately - don't wait for an N+1 problem to surface in production before adding DataLoader or an equivalent. Enforce query complexity limits and depth limiting so a malicious or poorly written client can't request an arbitrarily deep, expensive query that degrades the server for everyone else. And treat your schema as a genuine contract: use deprecation directives (@deprecated) to phase out fields gracefully rather than removing them outright, since GraphQL's single-endpoint model means there's no /v2 to fall back on if a client is still relying on an old field.

A practice that applies to both: whichever style you pick, invest in strong API documentation and contract testing. REST teams should adopt the OpenAPI (Swagger) specification to generate documentation and client SDKs automatically; GraphQL teams get much of this for free through introspection, but should still pair it with schema linting and automated breaking-change detection in CI.

Mental Models and Analogies

A useful way to frame the difference is to think of REST as ordering from a restaurant's fixed menu, and GraphQL as ordering from a buffet where you build your own plate. At the fixed-menu restaurant, each dish (endpoint) is prepared exactly one way; if you want the salad without the dressing, you either ask for a substitution the kitchen may or may not support, or you accept the dish as designed. At the buffet, you walk down the line and take precisely what you want - a component from here, a side from there - but the kitchen (server) now has to make everything available and efficiently servable in bulk to any combination a diner might choose, which is a harder operational problem than plating a fixed dish.

This analogy also explains why GraphQL servers need more resolver-layer engineering discipline: a buffet that lets you combine any dish with any other has to worry about someone taking sixty scoops of the most expensive item - which is precisely the query-complexity problem GraphQL servers guard against with depth and complexity limits. REST's fixed menu, in contrast, bounds the "cost" of a request by design, since the server decided the shape (and therefore the cost) of every dish in advance.

The 80/20 Insight

If you strip away the architectural nuance, most real-world REST-versus-GraphQL decisions come down to a small number of factors. The first is data shape volatility: if your client screens need to combine data from many resources in ways that change frequently as the product evolves, GraphQL's client-driven queries save enormous engineering time compared to constantly adding or reshaping REST endpoints. If your data access patterns are stable and resource-oriented, REST's simplicity wins by default.

The second factor is infrastructure leverage. If your system already depends heavily on HTTP-level caching - CDNs, reverse proxies, browser caches - REST lets you use that infrastructure for free, while GraphQL requires you to rebuild equivalent caching at the application layer. The third factor is team and ecosystem maturity: REST requires less specialized tooling and is easier to onboard new engineers into, while GraphQL's benefits - introspection, precise fetching, subscriptions - compound as an API's schema and client base grow large enough that the upfront tooling investment pays for itself. In practice, checking these three factors resolves the majority of REST-versus-GraphQL decisions without needing to weigh every secondary consideration.

Key Takeaways

Conclusion

REST and GraphQL aren't competing answers to the same question so much as two different questions about what an API should optimize for. REST optimizes for simplicity, cacheability, and alignment with the web's existing infrastructure; GraphQL optimizes for precise, flexible data retrieval and a strongly typed, self-documenting contract between client and server. Both are the right choice somewhere, and both can become the wrong choice if applied without considering how your specific data access patterns, caching needs, and team capacity actually behave.

The most durable architectural decisions come from naming these tradeoffs explicitly rather than picking based on what's trending. If your application's data is stable, resource-shaped, and cache-sensitive, REST will likely serve you well for years. If your clients need to compose complex, evolving views out of many related pieces of data - and you're willing to invest in the resolver-layer engineering GraphQL demands - it can meaningfully reduce both over-the-wire waste and the number of screen-specific endpoints your team maintains. Either way, the goal is the same: a contract that both your client and server teams can evolve confidently, without breaking each other along the way.

References

A quick flashcard preview - one example of each question type in this post. This is a demo of what you'll find in the full quiz app.

Flashcard preview · 1 / 9Multiple Choice

multiple choice - intermediate - auto-graded

A GraphQL team wants to retire the User.phoneNumber field in favor of User.contactInfo.phone, while several partner clients still actively query the old field. What is the recommended approach?

Choose an answer