REST vs GraphQL

REST and GraphQL both help apps talk to backends, but they divide responsibility differently. REST centers on backend-designed URLs, while GraphQL centers on client-written queries against a backend schema. This note compares their mental models, request shapes, Swift usage, tradeoffs, and when each approach fits best.

If you already know regular HTTP APIs, GraphQL is easier to understand as a different way for the client and backend to agree on data.

REST is more like:

The backend creates many endpoints, and the client requests a specific URL.

GraphQL is more like:

The backend provides a schema, and the client declares exactly what data it wants.

1. What Is REST?

REST APIs usually expose different resources through different URLs.

For example:

GET /countries/JP

The response might be:

{
  "code": "JP",
  "name": "Japan",
  "capital": "Tokyo",
  "currency": "JPY",
  "emoji": "🇯🇵",
  "languages": [
    {
      "code": "ja",
      "name": "Japanese"
    }
  ]
}

In Swift, a REST request often looks like this:

var request = URLRequest(url: url)
request.httpMethod = "GET"

let (data, response) = try await URLSession.shared.data(for: request)
let result = try JSONDecoder().decode(Country.self, from: data)

The key idea:

In REST, the backend endpoint usually decides the shape of the response.

2. What Is GraphQL?

GraphQL usually uses a single endpoint:

POST /graphql

The client sends a GraphQL query in the HTTP body:

{
  "query": "query GetCountry($code: ID!) { country(code: $code) { name capital } }",
  "variables": {
    "code": "JP"
  }
}

Written more clearly, the GraphQL query looks like this:

query GetCountry($code: ID!) {
  country(code: $code) {
    name
    capital
  }
}

This means:

Find the country whose code is JP.
Return only its name and capital.

The response matches the fields requested by the client:

{
  "data": {
    "country": {
      "name": "Japan",
      "capital": "Tokyo"
    }
  }
}

The key idea:

In GraphQL, the client declares the shape of the response.

3. The Core Difference

REST focuses on URLs:

GET /countries/JP

GraphQL focuses on queries:

query GetCountry($code: ID!) {
  country(code: $code) {
    name
    capital
  }
}

REST says:

Give me the data defined by this endpoint.

GraphQL says:

According to the schema, give me exactly these fields.

4. Field Selection

With REST, the response is usually fixed by the backend.

Maybe you only need this:

Japan

But the REST API might return much more:

{
  "code": "JP",
  "name": "Japan",
  "capital": "Tokyo",
  "currency": "JPY",
  "emoji": "🇯🇵",
  "languages": [...]
}

With GraphQL, you can request only the field you need:

query {
  country(code: "JP") {
    name
  }
}

Response:

{
  "data": {
    "country": {
      "name": "Japan"
    }
  }
}

This avoids over-fetching, which means receiving data you do not need.

5. Nested Data

With REST, nested or related data may require multiple requests:

GET /countries/JP
GET /countries/JP/languages
GET /countries/JP/continent

With GraphQL, you can request related data in one query:

query {
  country(code: "JP") {
    name
    capital
    languages {
      name
    }
    continent {
      name
    }
  }
}

This can reduce the number of network requests, especially on mobile apps where one screen may need data from multiple resources.

6. Operation Names and Variables

Consider this query:

query GetCountry($code: ID!) {
  country(code: $code) {
    name
  }
}

Breakdown:

query       The operation type. It reads data.
GetCountry  The operation name. You choose this name.
$code       A variable.
ID!         The variable type. ID means identifier, and ! means non-null.
country     A query field defined by the backend schema.
name        A field selected by the client.

The variables are sent separately:

{
  "code": "JP"
}

Important detail:

GraphQL variable: $code
JSON variable key: "code"

The JSON key does not include $.

You can also omit the operation name:

query ($code: ID!) {
  country(code: $code) {
    name
  }
}

You can also hardcode the argument:

query {
  country(code: "JP") {
    name
  }
}

But in real projects, this is usually preferred:

query GetCountry($code: ID!) {
  country(code: $code) {
    name
  }
}

Because named operations are easier to debug, log, and use with code generation tools.

7. Making a GraphQL Request in Swift

GraphQL is still just an HTTP request.

A REST request might look like this:

var request = URLRequest(url: url)
request.httpMethod = "GET"
request.addValue(apiKey, forHTTPHeaderField: "X-Riot-Token")

let (data, response) = try await URLSession.shared.data(for: request)

A GraphQL request usually looks like this:

import Foundation

struct GraphQLRequest: Encodable {
    let query: String
    let variables: [String: String]
}

let query = """
query GetCountry($code: ID!) {
  country(code: $code) {
    name
    capital
  }
}
"""

let body = GraphQLRequest(
    query: query,
    variables: ["code": "JP"]
)

var request = URLRequest(url: URL(string: "https://countries.trevorblades.com/")!)
request.httpMethod = "POST"
request.addValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try JSONEncoder().encode(body)

let (data, response) = try await URLSession.shared.data(for: request)

The important line is:

request.httpBody = try JSONEncoder().encode(body)

It sends this JSON to the server:

{
  "query": "...",
  "variables": {
    "code": "JP"
  }
}

8. Backend vs Client Responsibility

GraphQL does not mean the client can request anything it imagines.

The backend defines a schema:

type Country {
  code: ID!
  name: String!
  capital: String
}

type Query {
  country(code: ID!): Country
}

The client can only select fields that exist in the schema.

A useful way to think about it:

Backend defines the menu:
Available types, fields, arguments, and relationships.

Client orders from the menu:
Which fields it wants for this request.

9. REST vs GraphQL Comparison

Topic	REST	GraphQL
Endpoint	Usually many URLs	Usually one /graphql endpoint
Common HTTP Method	GET, POST, PUT, DELETE	Usually POST
Response Shape	Usually decided by the backend	Decided by the client query
Parameters	URL path, query string, or body	Variables in request body
Nested Data	May require multiple requests	Can be fetched in one query
Type System	Often documented separately	Built into the schema
Learning Curve	Lower	Higher
Caching	Works naturally with HTTP caching	Needs more specific strategy
Best For	Simple resource-based APIs	Apps that combine many related data types

10. When Should You Use REST?

REST is a good fit when:

The API is simple.
Resources are straightforward.
The response shape is stable.
The team already has mature REST conventions.
HTTP caching is important and simple URL-based caching works well.

Example:

GET /users/123
GET /posts/456
POST /login

REST is direct, familiar, and works very well for many APIs.

11. When Should You Use GraphQL?

GraphQL is a good fit when:

One screen needs data from many related resources.
Different clients need different fields.
The app wants to reduce over-fetching and under-fetching.
The team wants schema-driven development.
The team wants generated client models.

For iOS development, GraphQL is especially useful when a screen needs a carefully shaped set of data.

For example, a profile screen may need:

User name
Avatar
Recent posts
Follower count
Viewer relationship
Settings flags

With REST, that may require multiple endpoints.

With GraphQL, it can be one query.

12. Simple Mental Model

REST:

The client requests backend-designed URLs.

GraphQL:

The client requests fields from a backend-designed schema.

REST is like going to a fixed service window.

GraphQL is like ordering from a menu:

The backend writes the menu.
The client chooses what to order.

13. Final Summary

REST and GraphQL are both ways to build APIs.

REST is simpler and URL-centered.

GraphQL is more flexible and query-centered.

The biggest difference is not HTTP itself. Both can use HTTP.

The biggest difference is who controls the response shape:

REST:
The backend endpoint controls the response shape.

GraphQL:
The client query controls the response shape, within the backend schema.