REST vs GraphQL : Understand in 3 Minutes

#restvsgraphql #apicomparison #datafetching #abotwrotethis

Problem Statement

Choosing between REST and GraphQL is a fundamental design decision about how your client applications ask for data from an API. You encounter this problem when building or consuming an API and you start wrestling with issues like making too many network requests, receiving huge amounts of unnecessary data, or constantly bugging the backend team to create new endpoints for your specific needs.

Core Explanation

Think of an API as a kitchen and your app as a customer. REST is like ordering from a fixed menu. You request a specific item (a resource at a URL like /users/123), and the kitchen sends you the entire pre-plated dish they’ve decided on, which might include sides you didn't want. To get a complete view, you might need to order from several menus: one for the user, another for their posts (/users/123/posts), and another for their friends.

GraphQL is like giving the kitchen a custom order slip. You write down exactly what you want on a single sheet: "I want the user's name, their last three post titles, and their friends' profile pictures." The kitchen then prepares and sends back only that combination.

Here’s the breakdown:

REST operates on the concept of resources (like Users, Posts). You interact with them via standardized HTTP methods (GET, POST) at dedicated URLs. The server defines the structure of the data returned for each endpoint.
GraphQL has a single endpoint. The client sends a query (a structured request describing the desired data shape) to this endpoint. The server responds with a JSON object that matches the shape of the query, nothing more and nothing less.

Practical Context

Use REST when your API is simple, your data relationships are straightforward, and you benefit heavily from HTTP caching and tooling. It's excellent for stable, resource-oriented applications and when you want to leverage standard HTTP features fully.

Use GraphQL when you have complex, nested data requirements across multiple entities (like a dashboard), when you serve many different clients (mobile, web, IoT) with different data needs, or when you want to minimize the number of network requests from the client. It gives front-end developers more control and can reduce over-fetching.

Do not use GraphQL if your API is very simple, if you require simple HTTP caching, or if your team isn't prepared to handle the complexity of defining a strong schema and potentially more complex server-side resolvers.

Quick Example

Imagine you need a user's name and the titles of their recent blog posts.

With REST, you might make two calls:

GET /users/123
// Response: { id: 123, name: "Alex", email: "a@b.com", city: "London", ... }

GET /users/123/posts
// Response: [ {id: 1, title: "Post A", body: "...", comments: [...]}, ... ]

You over-fetch extra user fields and full post bodies.

With GraphQL, you make one query:

query {
  user(id: 123) {
    name
    posts(limit: 3) {
      title
    }
  }
}

The response is a perfect mirror of your request shape:

{
  "data": {
    "user": {
      "name": "Alex",
      "posts": [
        { "title": "Post A" },
        { "title": "Post B" }
      ]
    }
  }
}

This example demonstrates GraphQL's precision in fetching only the requested fields across related resources in a single request.

Key Takeaway

Choose REST for simplicity and standardized cacheability; choose GraphQL for efficient, client-driven data fetching in complex applications. Your decision should hinge on who you want to control the data shape: the server (REST) or the client (GraphQL). For a deeper dive, start with the official GraphQL introduction.

DEV Community