đź’Š tist
Back to blog
vi
•
9 min read

GraphQL vs. REST: A Front-End Face-Off

#api #frontend #programming

GraphQL vs. REST: The API Showdown

Choosing between GraphQL and REST for your API is like choosing between a buffet and a prix fixe menu. Both have their advantages and disadvantages, and the best choice depends on your project’s needs. This post compares the two API paradigms from a front-end developer’s perspective, focusing on data fetching, over-fetching/under-fetching, strong typing, developer experience, caching, and use cases.

Data Fetching: Efficiency and Flexibility

REST

In REST, you make multiple requests to different endpoints to fetch the data you need. It’s like ordering individual dishes from a menu. You might end up with more data than you need, or you might have to make multiple trips to the buffet (API) to get everything.

Example: Fetching User and Posts with REST

Suppose you need to fetch user information and their posts. With REST, you might have:

  • /users/123 to get user information.
  • /users/123/posts to get the user’s posts.

This requires two separate requests:

// Fetch user information
fetch("https://api.example.com/users/123")
  .then((response) => response.json())
  .then((data) => console.log(data));

// Fetch user's posts
fetch("https://api.example.com/users/123/posts")
  .then((response) => response.json())
  .then((data) => console.log(data));

GraphQL

With GraphQL, you send a single query to a single endpoint, specifying exactly what data you need. It’s like creating your own custom meal at the buffet. You get exactly what you want, no more, no less.

Example: Fetching User and Posts with GraphQL

Using a single GraphQL query, you can fetch both user information and their posts in one request:

# GraphQL query example
query {
  user(id: 123) {
    name
    email
    posts {
      title
      content
    }
  }
}

Example in JavaScript:

const query = `
  query {
    user(id: 123) {
      name
      email
      posts {
        title
        content
      }
    }
  }
`;

fetch("https://api.example.com/graphql", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query }),
})
  .then((response) => response.json())
  .then((data) => console.log(data));

Over-Fetching and Under-Fetching: The Data Dilemma

REST

One of the main drawbacks of REST is the potential for over-fetching and under-fetching:

  • Over-Fetching: You receive more data than you need, wasting bandwidth and potentially slowing down your app.
  • Under-Fetching: You don’t receive all the data you need, requiring additional requests to fetch more data.

Example: Over-Fetching in REST

Suppose you need only the user’s name and email. With REST, you might get a response with unnecessary fields:

{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": "12345"
  },
  "phone": "555-1234"
}

GraphQL

GraphQL solves the over-fetching and under-fetching problem by allowing you to request precisely the data you need. No more, no less. It’s like ordering a half-portion at a restaurant—you get exactly what you want without wasting food (or bandwidth).

Example: Fetching Only Required Fields in GraphQL

# GraphQL query example
query {
  user(id: 123) {
    name
    email
  }
}

This query fetches only the name and email fields of the user.

Strong Typing and Introspection: GraphQL’s Superpowers

REST

In REST, you typically rely on documentation to describe the API’s structure and data types. Documentation can be outdated or inaccurate, leading to confusion and errors. It’s like trying to assemble IKEA furniture without the instructions.

Example: REST Documentation

# User endpoint

GET /users/{id}

**Response:**
{
"id": "integer",
"name": "string",
"email": "string",
"address": {
"street": "string",
"city": "string",
"state": "string",
"zip": "string"
},
"phone": "string"
}

GraphQL

GraphQL has a strongly typed schema, which defines the types of data available and the relationships between them. This schema enables powerful introspection capabilities, allowing you to explore the API and discover what data is available. It’s like having a built-in IKEA instruction manual—clear, concise, and always up-to-date.

Example: GraphQL Schema

type User {
  id: ID!
  name: String!
  email: String!
  address: Address
  phone: String
}

type Address {
  street: String
  city: String
  state: String
  zip: String
}

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

Using Introspection in GraphQL:

# Introspection query
{
  __schema {
    types {
      name
      fields {
        name
        type {
          name
        }
      }
    }
  }
}

Developer Experience and Tooling: Making Life Easier

REST

Tooling and libraries for REST are widely available, but there can be inconsistencies and variations in how they work.

Example: REST Libraries

  • Axios: A popular HTTP client for making requests.
  • Fetch API: Built into modern browsers for making requests.

Using Axios in REST:

import axios from "axios";

axios
  .get("https://api.example.com/users/123")
  .then((response) => console.log(response.data))
  .catch((error) => console.error(error));

GraphQL

GraphQL has a rapidly growing ecosystem of tools and libraries, such as GraphiQL and Apollo Client, which provide features like autocompletion, schema exploration, and caching. These tools enhance the developer experience significantly.

Example: Apollo Client in GraphQL

# Install Apollo Client
npm install @apollo/client graphql

Setting Up Apollo Client:

import { ApolloClient, InMemoryCache, gql } from "@apollo/client";

const client = new ApolloClient({
  uri: "https://api.example.com/graphql",
  cache: new InMemoryCache(),
});

// Using the client to make a query
client
  .query({
    query: gql`
      query {
        user(id: 123) {
          name
          email
          posts {
            title
            content
          }
        }
      }
    `,
  })
  .then((response) => console.log(response.data))
  .catch((error) => console.error(error));

Caching: Saving Bandwidth and Time

REST

Caching in REST is relatively straightforward due to the use of multiple endpoints. Each endpoint can have its own caching strategy.

Example: REST Caching with Headers

fetch("https://api.example.com/users/123", {
  headers: {
    "Cache-Control": "max-age=3600", // Cache for 1 hour
  },
});

GraphQL

Caching in GraphQL can be more challenging because all requests go to a single endpoint. However, tools like Apollo Client offer sophisticated caching mechanisms to optimize performance.

Example: Apollo Client Caching

const client = new ApolloClient({
  uri: "https://api.example.com/graphql",
  cache: new InMemoryCache({
    typePolicies: {
      User: {
        keyFields: ["id"],
      },
    },
  }),
});

// Fetching data with caching
client
  .query({
    query: gql`
      query {
        user(id: 123) {
          name
          email
          posts {
            title
            content
          }
        }
      }
    `,
  })
  .then((response) => console.log(response.data))
  .catch((error) => console.error(error));

Use Cases: Picking the Right Tool for the Job

REST

REST is well-suited for:

  • Simple APIs: When your data model is straightforward and doesn’t change frequently.
  • Resource-Based Applications: When your API is organized around resources (e.g., users, posts).
  • Scenarios Where Caching is Critical: When minimizing data transfer and improving performance through caching is essential.

Example: REST in a Blogging Platform

A simple blogging platform with a REST API can define endpoints like:

  • /users to manage user data.
  • /posts to manage blog posts.

GraphQL

GraphQL is ideal for:

  • Complex Applications: When your application has evolving data requirements and interconnected data structures.
  • Mobile Apps: Where minimizing data transfer and optimizing performance is crucial.
  • Scenarios Where Flexibility is Key: When you need the ability to request only the data you need.

Example: GraphQL in a Mobile Application

A mobile app that requires frequent updates and access to various related data can use GraphQL to efficiently fetch data:

# GraphQL query for a mobile app
query {
  user(id: 123) {
    name
    email
    profilePicture
    posts(limit: 10) {
      title
      content
      comments(limit: 3) {
        user {
          name
        }
        text
      }
    }
  }
}

Case Study: Real Company XYZ

Let’s take a look at Real Company XYZ, a tech startup developing a social media platform. They initially used REST but faced challenges with over-fetching and under-fetching, leading to slower load times and increased bandwidth costs. They decided to switch to GraphQL to improve performance and developer efficiency. Here’s how they did it:

Before: Using REST

Endpoints:

  • /users/{id}
  • /users/{id}/posts
  • /posts/{id}/comments

Multiple Requests:

// Fetch user data
fetch("https://api.realcompanyxyz.com/users/123")
  .then((response) => response.json())
  .then((userData) => {
    console.log("User Data:", userData);

    // Fetch user's posts
    fetch(`https://api.realcompanyxyz.com/users/${userData.id}/posts`)
      .then((response) => response.json())
      .then((postsData) => {
        console.log("Posts Data:", postsData);
        postsData.forEach((post) => {
          // Fetch comments for each post
          fetch(`https://api.realcompanyxyz.com/posts/${post.id}/comments`)
            .then((response) => response.json())
            .then((commentsData) => {
              console.log("Comments Data:", commentsData);
            });
        });
      });
  });

After: Using GraphQL

Single Query:

# GraphQL query example
query {
  user(id: 123) {
    name
    email
    profilePicture
    posts(limit: 10) {
      title
      content
      comments(limit: 3) {
        user {
          name
        }
        text
      }
    }
  }
}

JavaScript Code:

import { ApolloClient, InMemoryCache, gql } from "@apollo/client";

const client = new ApolloClient({
  uri: "https://api.realcompanyxyz.com/graphql",
  cache: new InMemoryCache({
    typePolicies: {
      User: {
        keyFields: ["id"],
      },
      Post: {
        keyFields: ["id"],
      },
    },
  }),
});

client
  .query({
    query: gql`
      query {
        user(id: 123) {
          name
          email
          profilePicture
          posts(limit: 10) {
            title
            content
            comments(limit: 3) {
              user {
                name
              }
              text
            }
          }
        }
      }
    `,
  })
  .then((response) => console.log(response.data))
  .catch((error) => console.error(error));

By switching to GraphQL, Real Company XYZ reduced the number of requests from multiple to one, improved load times, and reduced bandwidth costs. The developers also benefited from the powerful schema and introspection features, making the development process more efficient and enjoyable.

Conclusion:

There’s no clear winner in the GraphQL vs. REST showdown. The best choice depends on your specific project needs and priorities.

  • REST: Ideal for simple APIs, resource-based applications, and situations where caching is critical.
  • GraphQL: Perfect for complex applications with evolving data requirements, mobile apps, and scenarios where minimizing data transfer is a priority.