REST vs GraphQL: Which API Architecture Should You Use?

The 6 REST Constraints

• Client-Server: The client and server are separate concerns. The client handles the UI; the server handles data storage and business logic. They communicate only through the API interface.
• Stateless: Each HTTP request from the client must contain all the information the server needs to process it. The server stores no client session state between requests.
• Cacheable: Responses must indicate whether they can be cached. Proper caching can eliminate client-server interaction entirely for repeated requests, improving performance significantly.
• Uniform Interface: All resources are identified by URLs; resources are manipulated through representations; messages are self-descriptive; hypermedia drives application state (HATEOAS).
• Layered System: The client does not need to know whether it is talking directly to the server or through intermediaries (load balancers, gateways, CDNs).
• Code on Demand (optional): Servers can extend client functionality by sending executable code (e.g. JavaScript).

Defining REST endpoints for a blog API

// REST API endpoint structure for a blog
GET    /users              —  Get all users
GET    /users/:id          —  Get a specific user
POST   /users              —  Create a new user
PUT    /users/:id          —  Update a user (full replacement)
PATCH  /users/:id          —  Update a user (partial update)
DELETE /users/:id          —  Delete a user

GET    /posts              —  Get all posts
GET    /posts/:id          —  Get a specific post
POST   /posts              —  Create a new post
DELETE /posts/:id          —  Delete a post

GET    /users/:id/posts    —  Get all posts by a specific user

Express REST API — Node.js server

const express = require('express');
const app = express();
app.use(express.json());

// Mock data
const users = [
  { id: 1, name: 'Jane Mugo', email: 'jane@example.com', role: 'admin' },
  { id: 2, name: 'Brian Ochieng', email: 'brian@example.com', role: 'user' },
];
const posts = [
  { id: 1, title: 'Intro to REST', authorId: 1, published: true },
  { id: 2, title: 'Why GraphQL?', authorId: 2, published: true },
  { id: 3, title: 'Draft Post', authorId: 1, published: false },
];

// GET all users
app.get('/users', (req, res) => {
  res.json(users);
});

// GET a specific user by ID
app.get('/users/:id', (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  if (!user) return res.status(404).json({ error: 'User not found' });
  res.json(user);
});

// POST create a new user
app.post('/users', (req, res) => {
  const { name, email, role = 'user' } = req.body;
  if (!name || !email) {
    return res.status(400).json({ error: 'Name and email are required' });
  }
  const newUser = { id: users.length + 1, name, email, role };
  users.push(newUser);
  res.status(201).json(newUser);
});

// PATCH update specific fields of a user
app.patch('/users/:id', (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  if (!user) return res.status(404).json({ error: 'User not found' });
  Object.assign(user, req.body);
  res.json(user);
});

// DELETE a user
app.delete('/users/:id', (req, res) => {
  const index = users.findIndex(u => u.id === parseInt(req.params.id));
  if (index === -1) return res.status(404).json({ error: 'User not found' });
  users.splice(index, 1);
  res.status(204).send();
});

// GET all posts by a specific user
app.get('/users/:id/posts', (req, res) => {
  const userPosts = posts.filter(p => p.authorId === parseInt(req.params.id));
  res.json(userPosts);
});

app.listen(3000, () => console.log('REST API running on port 3000'));

Client-side: Calling a REST API from React

// Fetch a user and their posts in React
import { useState, useEffect } from 'react';

function UserProfile({ userId }) {
  const [user, setUser] = useState(null);
  const [posts, setPosts] = useState([]);

  useEffect(() => {
    // Two separate requests needed to get user + their posts
    Promise.all([
      fetch(`/users/${userId}`).then(r => r.json()),
      fetch(`/users/${userId}/posts`).then(r => r.json()),
    ]).then(([userData, postsData]) => {
      setUser(userData);
      setPosts(postsData);
    });
  }, [userId]);

  if (!user) return <p>Loading...</p>;

  return (
    <div>
      <h2>{user.name}</h2>
      <p>{user.email}</p>
      <h3>Posts</h3>
      {posts.map(post => <p key={post.id}>{post.title}</p>)}
    </div>
  );
}

Notice that to get a user and their posts, we need two separate HTTP requests. This is a common REST pattern — and one of the friction points that GraphQL was designed to address.

The three GraphQL operation types

• Query: Read data (equivalent to REST GET). The client specifies which fields it wants returned.
• Mutation: Write data — create, update, or delete (equivalent to REST POST, PUT, PATCH, DELETE).
• Subscription: Subscribe to real-time data changes. The server pushes updates to the client over a WebSocket connection whenever the specified data changes.

GraphQL Schema Definition

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

// Define the schema using GraphQL Schema Definition Language (SDL)
const typeDefs = gql`
  type User {
    id: ID!
    name: String!
    email: String!
    role: String!
    posts: [Post!]!
  }

  type Post {
    id: ID!
    title: String!
    published: Boolean!
    author: User!
  }

  type Query {
    users: [User!]!
    user(id: ID!): User
    posts: [Post!]!
    post(id: ID!): Post
  }

  type Mutation {
    createUser(name: String!, email: String!, role: String): User!
    updateUser(id: ID!, name: String, email: String): User
    deleteUser(id: ID!): Boolean!
    createPost(title: String!, authorId: ID!): Post!
  }

  type Subscription {
    postCreated: Post!
  }
`;

Resolvers — the functions that execute each query

const users = [
  { id: '1', name: 'Jane Mugo', email: 'jane@example.com', role: 'admin' },
  { id: '2', name: 'Brian Ochieng', email: 'brian@example.com', role: 'user' },
];
const posts = [
  { id: '1', title: 'Intro to REST', authorId: '1', published: true },
  { id: '2', title: 'Why GraphQL?', authorId: '2', published: true },
];

const resolvers = {
  Query: {
    users: () => users,
    user: (_, { id }) => users.find(u => u.id === id),
    posts: () => posts,
    post: (_, { id }) => posts.find(p => p.id === id),
  },

  Mutation: {
    createUser: (_, { name, email, role = 'user' }) => {
      const newUser = { id: String(users.length + 1), name, email, role };
      users.push(newUser);
      return newUser;
    },
    deleteUser: (_, { id }) => {
      const index = users.findIndex(u => u.id === id);
      if (index === -1) return false;
      users.splice(index, 1);
      return true;
    },
    createPost: (_, { title, authorId }) => {
      const newPost = { id: String(posts.length + 1), title, authorId, published: false };
      posts.push(newPost);
      return newPost;
    },
  },

  // Field resolvers — how to fetch related data
  User: {
    posts: (parent) => posts.filter(p => p.authorId === parent.id),
  },
  Post: {
    author: (parent) => users.find(u => u.id === parent.authorId),
  },
};

const server = new ApolloServer({ typeDefs, resolvers });
server.listen().then(({ url }) => console.log(`GraphQL server at ${url}`));

GraphQL Queries from the client

Get user name and email only (no over-fetching):

query {
  user(id: "1") {
    name
    email
  }
}

Get user with their posts in a single query (no under-fetching):

query {
  user(id: "1") {
    name
    email
    posts {
      id
      title
      published
    }
  }
}

Create a new user (mutation):

mutation {
  createUser(name: "Alice Wanjiku", email: "alice@example.com") {
    id
    name
    email
  }
}

Using Apollo Client in React:

import { useQuery, gql } from '@apollo/client';

const GET_USER_WITH_POSTS = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      name
      email
      posts {
        id
        title
        published
      }
    }
  }
`;

function UserProfile({ userId }) {
  const { loading, error, data } = useQuery(GET_USER_WITH_POSTS, {
    variables: { id: userId },
  });

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  const { user } = data;

  return (
    <div>
      <h2>{user.name}</h2>
      <p>{user.email}</p>
      <h3>Posts</h3>
      {user.posts.map(post => <p key={post.id}>{post.title}</p>)}
    </div>
  );
}

Note that this single GraphQL query replaces the two separate REST requests needed in the earlier example — and the response contains only the fields explicitly requested.

Over-fetching scenario

You are building a user list page that only needs to show each user's name and profile picture. Your REST API has a GET /users endpoint that returns:

[
  {
    "id": 1,
    "name": "Jane Mugo",
    "email": "jane@example.com",
    "role": "admin",
    "bio": "Full-stack developer based in Nairobi...",
    "address": { "city": "Nairobi", "country": "Kenya" },
    "preferences": { "theme": "dark", "notifications": true },
    "createdAt": "2024-01-15T08:30:00Z",
    "lastLoginAt": "2026-03-10T14:22:00Z"
  }
  // ... many more users
]

Your page only needs name — but the API sends all 10 fields for every user. On a mobile connection, this extra data meaningfully increases load time and data usage. With GraphQL you would request exactly { users { id name } } and receive nothing extra.

Under-fetching scenario

You are building a product page that needs: the product details, the seller's name, and the top 3 reviews. With REST you need three separate API calls:

// Request 1: Get the product
GET /products/42
// Response: product data (but no seller or reviews)

// Request 2: Get the seller
GET /users/7
// Response: seller data

// Request 3: Get the reviews
GET /products/42/reviews?limit=3
// Response: review data

Three HTTP round trips, each with its own latency. With GraphQL, one query retrieves everything:

query {
  product(id: "42") {
    name
    price
    description
    seller {
      name
    }
    reviews(limit: 3) {
      rating
      comment
      author { name }
    }
  }
}

The N+1 problem — and the DataLoader solution

// ’R Naive resolver — triggers N+1 queries
const resolvers = {
  Post: {
    author: (post) => {
      // This runs once for EACH post — 10 posts = 10 DB queries!
      return db.query('SELECT * FROM users WHERE id = ?', [post.authorId]);
    }
  }
};

// “& With DataLoader — batches into 1 query
const DataLoader = require('dataloader');

const userLoader = new DataLoader(async (userIds) => {
  // DataLoader collects all IDs from one tick, then calls this once
  const users = await db.query('SELECT * FROM users WHERE id IN (?)', [userIds]);
  // Return users in the same order as the IDs
  return userIds.map(id => users.find(u => u.id === id));
});

const resolvers = {
  Post: {
    author: (post) => userLoader.load(post.authorId)
    // All 10 author loads are batched into one query
  }
};

DataLoader is a utility that batches multiple individual load calls into a single batch request within a single event loop tick. It's the standard solution for the N+1 problem in GraphQL.

REST security considerations

• Standard HTTP authentication (JWT in Authorization header, OAuth 2.0, API keys) applies directly
• Endpoint-level authorization is straightforward — middleware can protect entire routes
• Rate limiting by endpoint and IP is well-understood and widely supported by infrastructure (nginx, API gateways)
• HTTPS, CORS, and CSRF protection follow well-established HTTP patterns

GraphQL-specific security risks

• Query depth attacks: Deeply nested queries can cause exponential database load. Always set a maximum query depth limit (typically 5—10 levels).
• Query complexity attacks: A single query requesting 1,000 nested objects can overwhelm the server. Implement query complexity scoring and reject queries exceeding a threshold.
• Introspection in production: GraphQL's schema introspection is useful for development but exposes your full API surface to attackers in production. Disable or restrict introspection in production environments.
• Field-level authorization: In REST, authorization is at the endpoint level. In GraphQL, you need to authorize individual fields — a user might be allowed to query their own email but not other users' emails.

Choose REST when:

• You are building a simple CRUD API with well-defined, stable resource shapes
• Your team has strong REST experience and limited GraphQL knowledge — the productivity cost of learning GraphQL outweighs the benefits
• You are building a public API for third-party developers — REST's simplicity and HTTP familiarity lower the barrier for external consumers
• HTTP caching is critical for your performance strategy — content-heavy sites, CDN-served resources, public data
• Your backend is a simple microservice with 5—10 endpoints that is unlikely to grow in complexity
• You are building a mobile app backend with a small, stable set of data requirements

Common hybrid patterns

• GraphQL as an API gateway over REST microservices: Each individual microservice exposes a REST API internally. A GraphQL gateway wraps all of them, giving the frontend a single GraphQL interface while each backend service remains REST. This is the pattern used by many large companies.
• REST for public API, GraphQL for frontend: Keep a simple, documented REST API for third-party developers and public consumers. Use GraphQL internally for the web and mobile frontends that need complex data fetching.
• REST for webhooks and event delivery, GraphQL for queries: Use REST POST endpoints for webhooks and callbacks (Stripe payment webhooks, M-Pesa callbacks) while using GraphQL for the query interface.