REST vs GraphQL: A Practical Comparison

When to Use REST

REST has been the standard for API design for over a decade. It uses HTTP methods (GET, POST, PUT, DELETE) and resource-based URLs. REST is great when:

• You have simple, CRUD-heavy operations
• You want to leverage HTTP caching (e.g., GET requests can be cached)
• Your API consumers are varied (web, mobile, third-party)
• You need a straightforward, well-understood architecture

Example REST Endpoints

GET /api/users/123
GET /api/users/123/posts
POST /api/users
PUT /api/users/123
DELETE /api/users/123

REST works well for public APIs where you want to enforce a fixed schema. However, it suffers from over-fetching and under-fetching. For example, if a mobile client only needs a user's name and email, a REST endpoint that returns the full user object wastes bandwidth.

When to Use GraphQL

GraphQL, developed by Facebook, gives clients the power to ask for exactly what they need. It uses a single endpoint and a query language. GraphQL shines when:

• You have complex, nested data relationships (e.g., user -> posts -> comments)
• Your clients have varying data needs (mobile vs. desktop)
• You want rapid iteration on the frontend without backend changes
• You need to aggregate data from multiple sources

Example GraphQL Query

query {
  user(id: "123") {
    name
    email
    posts {
      title
      comments {
        text
      }
    }
  }
}

This query fetches only the requested fields, avoiding over-fetching. The response is predictable and matches the query structure.

Practical Trade-offs

Over-fetching and Under-fetching

REST often leads to over-fetching (getting too much data) or under-fetching (needing multiple requests). GraphQL solves this but introduces complexity: you need a resolver for every field, which can lead to N+1 queries if not optimized (use DataLoader).

Caching

REST benefits from HTTP caching (e.g., with ETags or Cache-Control). GraphQL typically uses a single POST endpoint, making caching harder. Solutions like persisted queries or CDN-level caching can help, but they add complexity.

Tooling and Ecosystem

REST has mature tooling (Swagger, Postman, etc.). GraphQL has excellent tools like Apollo Client, GraphiQL, and code generation. Both are well-supported, but GraphQL's tooling is more modern.

Learning Curve

REST is simpler to learn and debug. GraphQL requires understanding schemas, resolvers, and query optimization. For a small team or simple API, REST is often the better choice.

Code Example: Node.js Comparison

REST with Express

const express = require('express');
const app = express();

app.get('/api/users/:id', (req, res) => {
  const user = db.getUser(req.params.id);
  res.json(user);
});

app.listen(3000);

GraphQL with Apollo Server

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

const typeDefs = gql`
  type User {
    id: ID!
    name: String
    email: String
  }
  type Query {
    user(id: ID!): User
  }
`;

const resolvers = {
  Query: {
    user: (_, { id }) => db.getUser(id),
  },
};

const server = new ApolloServer({ typeDefs, resolvers });
server.listen(4000);

GraphQL requires more boilerplate but gives flexibility.

My Recommendation

Start with REST if your API is simple or you need broad interoperability. Switch to GraphQL when you face over-fetching/under-fetching issues or when your frontend teams need more autonomy. Many projects use both: REST for public endpoints and GraphQL for internal use.

Ultimately, choose based on your specific needs, not hype.