Introduction to GraphQL: A Comparison with REST API

Introduction

When designing Web APIs, many developers have used REST (Representational State Transfer) architecture as the standard. However, as applications have become more complex and diverse clients (Web, mobile apps, etc.) have emerged, several challenges inherent in REST APIs have become apparent.

In this article, we will explain GraphQL, which has been attracting attention as a technology to solve these challenges, from the basics through a comparison with REST APIs. This content is ideal for those looking for new options in API design or wanting to streamline the collaboration between frontend and backend.

What is GraphQL?

GraphQL is a query language for APIs and a server-side runtime for executing those queries, developed by Facebook (now Meta) and open-sourced in 2015. While REST is based on the concept of "resources," GraphQL's primary characteristic is that the client can flexibly specify the data it needs.

The client sends a query to the server describing the structure of the required data, much like querying a database. The server interprets that query and returns the data in a single request, without excess or deficiency. This solves the issues of "Over-fetching" and "Under-fetching" that frequently occur with REST.

Summary: Key Differences between REST API and GraphQL 📊

Before diving into the details, let's review the fundamental differences between REST API and GraphQL in a comparison table. Through this article, you will understand how the following points are realized.

Feature	REST API	GraphQL
Endpoints	Multiple endpoints (e.g., /users, /posts)	Usually a single endpoint (e.g., /graphql)
Data Fetching	Fixed data structure defined by the server	Client specifies required data via queries
Fetch Efficiency	Multiple requests may be needed for related data	Related data can be fetched at once in a single request
Challenges	Over-fetching and Under-fetching are common	Solved by allowing flexible data selection on the client side
Schema	Defined separately (e.g., OpenAPI)	Built-in strict type system (schema)

Architecture comparison between REST API and GraphQL

Challenges of REST API

To understand why GraphQL was created, let's look at two representative challenges faced by REST APIs.

1. Over-fetching
   Imagine a situation where you only need names in a list of users. If the REST API's /users endpoint is designed to return all properties, such as addresses and phone numbers in addition to names, the client ends up receiving unnecessary data. This leads to decreased performance, especially in environments with limited network bandwidth, such as mobile apps.

2. Under-fetching and the N+1 Problem
   If you want to display a blog post and its comments, you might need multiple requests: first fetching the post with /posts/:id, and then fetching the comments with /posts/:id/comments. This is called "Under-fetching" and affects the application's display speed. In particular, when fetching additional data for each item in a list (the N+1 problem), the number of requests can explode.

Three Key Concepts of GraphQL

GraphQL is composed of three main concepts to solve these challenges.

GraphQL Query Execution Flow

1. Schema
   The schema defines the types of data available in the GraphQL API. It acts like a contract that strictly defines "what queries can be executed." It is written using the Schema Definition Language (SDL), and the API specifications are managed as code.

2. Query
   A request sent by the client to the server to fetch data. It uses a syntax similar to JSON to describe the required data and its structure. Mutations are used for updating data, and Subscriptions are used for real-time communication.

3. Resolver
   A function corresponding to each field in the schema, responsible for the logic that actually fetches and processes data. It defines which database or API to fetch data from and return when a specific field's data is requested.

Implementation Example: Node.js and Apollo Server 💻

Let's look at an implementation example using Apollo Server, a library that allows you to easily build a GraphQL server.

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';

// 1. Schema definition (SDL)
const typeDefs = `#graphql
  # Define the "Book" type
  type Book {
    title: String
    author: String
  }

  # Define the "books" query
  type Query {
    books: [Book]
  }
`;

// Dummy data
const books = [
  {
    title: 'The Awakening',
    author: 'Kate Chopin',
  },
  {
    title: 'City of Glass',
    author: 'Paul Auster',
  },
];

// 2. Resolver definition
const resolvers = {
  Query: {
    books: () => books, // Return the books array when the "books" query is called
  },
};

// 3. Create ApolloServer instance
const server = new ApolloServer({
  typeDefs,
  resolvers,
});

// 4. Start the server
const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
});

console.log(`🚀  Server ready at: ${url}`);

By executing this code, the client can send a query like the one below to fetch only the necessary data.

query GetBooks {
  books {
    title
  }
}

When to Choose GraphQL

Not all APIs are suitable for GraphQL. GraphQL truly demonstrates its value in the following situations:

• Applications with diverse clients: When there are multiple clients (Web, iOS, Android, etc.) with different display requirements.
• Complex data requirements: When you need to fetch related data from multiple data sources.
• Network bandwidth is critical: When you want to minimize data usage, such as in mobile apps.
• Separation of frontend and backend: When you want the frontend team to be able to freely fetch the data they need without waiting for backend changes.

Conclusion

In this article, we explained the basic concepts of GraphQL and its benefits through a comparison with REST APIs. GraphQL is a powerful choice in API design and has the potential to significantly improve the efficiency of modern application development.

As a next step, we recommend actually building a simple GraphQL API using libraries such as Apollo Server or Relay. We encourage you to experience its flexibility and power firsthand through schema design and resolver implementation!