API Design

GraphQL vs REST in 2024: Making the Right Choice

A comprehensive comparison of GraphQL and REST APIs, helping you choose the right technology for your next project.

By API Team October 8, 2024 15 min read
GraphQL vs REST in 2024: Making the Right Choice

Choosing the right API architecture for modern applications

Introduction

The debate between GraphQL and REST has evolved significantly since GraphQL’s introduction by Facebook in 2015. In 2024, both technologies have matured, with clear use cases, tooling ecosystems, and best practices. This article provides a comprehensive comparison to help you make an informed decision for your next project.

Understanding the Fundamentals

REST (Representational State Transfer)

REST is an architectural style that treats server-side data as resources that can be accessed and manipulated using a standard set of operations.

Core Principles:

  • Resources: Everything is a resource identified by URIs
  • HTTP Methods: GET, POST, PUT, DELETE, PATCH
  • Stateless: Each request contains all information needed
  • Client-Server: Clear separation of concerns
  • Cacheable: Responses must define themselves as cacheable or not

Example REST API:

GET /api/users/123
GET /api/users/123/posts
GET /api/posts/456/comments

GraphQL

GraphQL is a query language and runtime for APIs that allows clients to request exactly what data they need.

Core Concepts:

  • Schema: Strongly typed schema defining API capabilities
  • Single Endpoint: Typically /graphql
  • Query Language: Clients specify exactly what they need
  • Resolver Functions: Server-side functions that fetch data

Example GraphQL Query:

query GetUserWithPosts {
  user(id: "123") {
    name
    email
    posts(limit: 5) {
      title
      content
      comments {
        text
        author {
          name
        }
      }
    }
  }
}

Key Differences

Data Fetching

REST: Multiple Round Trips

// REST: Multiple requests needed
const user = await fetch('/api/users/123');
const posts = await fetch(`/api/users/123/posts`);
const comments = await Promise.all(
  posts.map(p => fetch(`/api/posts/${p.id}/comments`))
);

GraphQL: Single Request

// GraphQL: One request gets everything
const query = `
  query {
    user(id: "123") {
      name
      posts {
        title
        comments {
          text
        }
      }
    }
  }
`;
const result = await graphqlClient.request(query);

Over-fetching and Under-fetching

REST Challenge:

// GET /api/users/123
// Returns ALL user fields even if you only need name
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "555-0100",
  "address": { /* ... */ },
  "preferences": { /* ... */ },
  "createdAt": "2024-01-01",
  "updatedAt": "2024-01-15"
  // ... many more fields
}

GraphQL Solution:

# Request only what you need
query {
  user(id: "123") {
    name  # Only returns name field
  }
}

Performance Considerations

REST Performance Optimizations

1. HTTP/2 Server Push:

// Express.js with HTTP/2 push
app.get('/api/users/:id', (req, res) => {
  const user = getUser(req.params.id);
  
  // Proactively push related resources
  if (res.push) {
    res.push(`/api/users/${req.params.id}/posts`, {
      method: 'GET',
      headers: { 'content-type': 'application/json' }
    }).end(JSON.stringify(getUserPosts(req.params.id)));
  }
  
  res.json(user);
});

2. Field Filtering:

GET /api/users/123?fields=name,email
GET /api/posts?fields=title,author&expand=comments

GraphQL Performance Challenges

N+1 Query Problem:

// Naive resolver implementation causes N+1 queries
const resolvers = {
  User: {
    posts: (user) => {
      // This runs for EACH user - N+1 problem!
      return db.query('SELECT * FROM posts WHERE user_id = ?', [user.id]);
    }
  }
};

// Solution: DataLoader for batching
const postLoader = new DataLoader(async (userIds) => {
  const posts = await db.query(
    'SELECT * FROM posts WHERE user_id IN (?)',
    [userIds]
  );
  return userIds.map(id => posts.filter(p => p.user_id === id));
});

const resolvers = {
  User: {
    posts: (user) => postLoader.load(user.id)
  }
};

Query Complexity Analysis:

// Prevent expensive queries with depth limiting
const depthLimit = require('graphql-depth-limit');
const costAnalysis = require('graphql-cost-analysis');

const server = new ApolloServer({
  typeDefs,
  resolvers,
  validationRules: [
    depthLimit(5),  // Max query depth
    costAnalysis({
      maximumCost: 1000,
      defaultCost: 1,
      scalarCost: 1,
      objectCost: 2,
      listFactor: 10
    })
  ]
});

Caching Strategies

REST Caching

REST’s resource-based model works excellently with HTTP caching:

// Server-side caching headers
app.get('/api/users/:id', (req, res) => {
  const user = getUser(req.params.id);
  
  res.set({
    'Cache-Control': 'public, max-age=3600',
    'ETag': generateETag(user),
    'Last-Modified': user.updatedAt
  });
  
  res.json(user);
});

// CDN configuration (CloudFlare example)
const cacheRules = {
  '/api/users/*': {
    cacheTTL: 3600,
    cacheKey: ['uri', 'headers:Authorization']
  },
  '/api/posts/*': {
    cacheTTL: 300,
    cacheKey: ['uri', 'query_string']
  }
};

GraphQL Caching

GraphQL caching is more complex due to its flexible query nature:

// Apollo Server with Redis cache
const server = new ApolloServer({
  typeDefs,
  resolvers,
  cache: new RedisCache({
    host: 'redis-server',
  }),
  plugins: [
    responseCachePlugin({
      sessionId: (requestContext) => 
        requestContext.request.http.headers.get('session-id'),
    }),
  ],
});

// Client-side normalized caching
const client = new ApolloClient({
  cache: new InMemoryCache({
    typePolicies: {
      User: {
        keyFields: ['id'],
        fields: {
          posts: {
            merge(existing = [], incoming) {
              return [...existing, ...incoming];
            }
          }
        }
      }
    }
  })
});

Real-Time Updates

REST: WebSockets/SSE

// Server-Sent Events for real-time updates
app.get('/api/users/:id/stream', (req, res) => {
  res.writeHead(200, {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    'Connection': 'keep-alive'
  });

  const unsubscribe = userChangeStream.subscribe(req.params.id, (data) => {
    res.write(`data: ${JSON.stringify(data)}\n\n`);
  });

  req.on('close', unsubscribe);
});

// Client-side
const eventSource = new EventSource('/api/users/123/stream');
eventSource.onmessage = (event) => {
  const userData = JSON.parse(event.data);
  updateUI(userData);
};

GraphQL: Subscriptions

# GraphQL Subscription
subscription OnUserUpdate($userId: ID!) {
  userUpdated(userId: $userId) {
    id
    name
    status
    lastActivity
  }
}

// Server implementation
const resolvers = {
  Subscription: {
    userUpdated: {
      subscribe: (_, { userId }, { pubsub }) => 
        pubsub.asyncIterator([`USER_UPDATED_${userId}`])
    }
  },
  Mutation: {
    updateUser: async (_, { id, input }, { pubsub }) => {
      const user = await updateUserInDB(id, input);
      pubsub.publish(`USER_UPDATED_${id}`, { userUpdated: user });
      return user;
    }
  }
};

Error Handling

REST Error Handling

// Consistent error responses
class APIError extends Error {
  constructor(status, code, message, details = {}) {
    super(message);
    this.status = status;
    this.code = code;
    this.details = details;
  }
}

app.get('/api/users/:id', async (req, res, next) => {
  try {
    const user = await getUser(req.params.id);
    if (!user) {
      throw new APIError(404, 'USER_NOT_FOUND', 'User not found');
    }
    res.json(user);
  } catch (error) {
    next(error);
  }
});

// Error middleware
app.use((error, req, res, next) => {
  const status = error.status || 500;
  res.status(status).json({
    error: {
      code: error.code || 'INTERNAL_ERROR',
      message: error.message,
      details: error.details,
      timestamp: new Date().toISOString()
    }
  });
});

GraphQL Error Handling

// GraphQL errors with extensions
const resolvers = {
  Query: {
    user: async (_, { id }) => {
      const user = await getUser(id);
      if (!user) {
        throw new GraphQLError('User not found', {
          extensions: {
            code: 'USER_NOT_FOUND',
            http: { status: 404 }
          }
        });
      }
      return user;
    }
  }
};

// Response with partial data and errors
{
  "data": {
    "user": {
      "name": "John Doe",
      "posts": null  // Failed to load
    }
  },
  "errors": [
    {
      "message": "Failed to fetch posts",
      "path": ["user", "posts"],
      "extensions": {
        "code": "SERVICE_UNAVAILABLE"
      }
    }
  ]
}

Versioning Strategies

REST Versioning

// URL versioning
app.use('/api/v1', v1Routes);
app.use('/api/v2', v2Routes);

// Header versioning
app.use((req, res, next) => {
  const version = req.headers['api-version'] || 'v1';
  req.apiVersion = version;
  next();
});

// Content negotiation
app.get('/api/users/:id', (req, res) => {
  const accept = req.headers.accept;
  if (accept.includes('application/vnd.api.v2+json')) {
    res.json(getUserV2(req.params.id));
  } else {
    res.json(getUserV1(req.params.id));
  }
});

GraphQL Evolution

# GraphQL schema evolution without versions
type User {
  id: ID!
  name: String!
  email: String! @deprecated(reason: "Use emailAddress instead")
  emailAddress: String!  # New field
  
  # Optional field with default
  preferences: UserPreferences
}

# Field arguments for backwards compatibility
type Query {
  users(
    format: UserFormat = COMPACT  # Default maintains old behavior
  ): [User!]!
}

enum UserFormat {
  COMPACT
  DETAILED
  FULL
}

Use Case Analysis

When to Choose REST

Perfect for:

  • Public APIs: Well-understood, standard conventions
  • Simple CRUD Operations: Resource-based operations
  • Cache-Heavy Systems: CDN and browser caching
  • File Uploads: Multipart form data support
  • Microservices: Service-to-service communication

Example: E-commerce Product API

// REST excels at cacheable, resource-based operations
GET    /api/products          // List products (cacheable)
GET    /api/products/123       // Get product (cacheable)
POST   /api/products           // Create product
PUT    /api/products/123       // Update product
DELETE /api/products/123       // Delete product
GET    /api/products/123/reviews  // Product reviews (cacheable)

When to Choose GraphQL

Perfect for:

  • Complex Data Requirements: Nested, related data
  • Mobile Applications: Bandwidth optimization
  • Rapid Frontend Development: Frontend teams can work independently
  • Real-time Applications: Built-in subscriptions
  • Dashboard/Analytics: Flexible data aggregation

Example: Social Media Feed

# GraphQL excels at complex, nested queries
query GetFeed {
  currentUser {
    feed(first: 20) {
      posts {
        id
        content
        author {
          name
          avatar
        }
        likes {
          count
          hasLiked
        }
        comments(first: 3) {
          text
          author {
            name
          }
        }
      }
    }
  }
}

Hybrid Approaches

REST + GraphQL

Many organizations successfully use both:

// REST for public API
app.use('/api/v1', restRoutes);

// GraphQL for internal/mobile clients
app.use('/graphql', apolloServer.middleware());

// REST endpoint that returns GraphQL-like responses
app.get('/api/users/:id', async (req, res) => {
  const fields = req.query.fields?.split(',') || ['*'];
  const expand = req.query.expand?.split(',') || [];
  
  const user = await getUserWithFields(req.params.id, fields, expand);
  res.json(user);
});

GraphQL Gateway over REST

// GraphQL gateway aggregating REST services
const resolvers = {
  Query: {
    user: async (_, { id }) => {
      const [user, posts, followers] = await Promise.all([
        fetch(`${USER_SERVICE}/users/${id}`).then(r => r.json()),
        fetch(`${POST_SERVICE}/users/${id}/posts`).then(r => r.json()),
        fetch(`${SOCIAL_SERVICE}/users/${id}/followers`).then(r => r.json())
      ]);
      
      return { ...user, posts, followers };
    }
  }
};

Decision Framework

Choose REST When:

  1. Simple CRUD operations dominate your API
  2. HTTP caching is critical for performance
  3. API consumers are diverse and unknown
  4. Team expertise is stronger in REST
  5. Infrastructure is optimized for REST (CDNs, gateways)

Choose GraphQL When:

  1. Data requirements are complex and varied
  2. Multiple clients need different data shapes
  3. Rapid iteration on frontend is needed
  4. Network efficiency is critical (mobile)
  5. Real-time updates are core to the application

Consider Both When:

  1. Different use cases require different approaches
  2. Migration path from REST to GraphQL is needed
  3. Public API (REST) and internal API (GraphQL)
  4. Team resources allow maintaining both

Conclusion

In 2024, the REST vs GraphQL debate isn’t about which is better—it’s about which is better for your specific use case. REST remains excellent for resource-based APIs with strong caching needs, while GraphQL shines in complex data scenarios with varied client requirements.

The best architectures often combine both technologies, leveraging REST’s simplicity and caching for public APIs while using GraphQL’s flexibility for complex internal operations. Understanding the strengths and weaknesses of each allows you to make informed decisions that align with your technical requirements, team capabilities, and business goals.

As both technologies continue to evolve—REST with HTTP/3 and GraphQL with improved tooling and federation—the key is to remain pragmatic, choosing the right tool for the right job rather than following trends blindly.

Tags

GraphQL REST API Web Development Architecture