GraphQL vs REST: When to Use Which

The schema: a typed menu

A GraphQL server publishes a schema. A schema is a written description of every type of data and how the types connect, like a menu:

type User {  id: ID!  name: String!  avatarUrl: String  loyaltyPoints: Int!  orders(last: Int): [Order!]!}type Order {  id: ID!  total: Int!  createdAt: String!  items: [OrderItem!]!}type OrderItem {  quantity: Int!  product: Product!}type Product {  id: ID!  name: String!  thumbnailUrl: String}type Query {  user(id: ID!): User}type Mutation {  updateProfile(name: String, avatarUrl: String): User!}

(! means "never null", so the value is always there. [Order!]! means a list that is never null and has no null items. ID is a unique identifier.)

Queries: ask for exactly what you need

A query reads data. You send one request to a single endpoint (usually POST /graphql):

query ProfileScreen {  user(id: "42") {    name    avatarUrl    loyaltyPoints    orders(last: 3) {      total      items {        product { name thumbnailUrl }      }    }  }}

The response has exactly that shape:

{  "data": {    "user": {      "name": "Asha",      "avatarUrl": "…/42.jpg",      "loyaltyPoints": 1250,      "orders": [        { "total": 129900, "items": [ { "product": { "name": "Running shoes", "thumbnailUrl": "…" } } ] }      ]    }  }}

Six REST calls became one request, with no wasted fields.

Mutations and subscriptions

• Mutations are operations that change data (like POST, PUT and DELETE in REST):
  GraphQLCopy

  mutation { updateProfile(name: "Asha K") { id name } }

• Subscriptions are long-lived requests that push new data to the client when something changes. They usually run over WebSockets (a two-way connection that stays open):
  GraphQLCopy

  subscription { orderStatusChanged(orderId: "5521") { status } }

Resolvers: how the server fills in the data

On the server, each field has a resolver. A resolver is a function that knows how to get the value of that one field:

const resolvers = {  Query: {    user: (_, { id }) => db.users.findById(id),  },  User: {    orders: (user, { last }) => db.orders.findRecent(user.id, last),    loyaltyPoints: (user) => loyaltyService.getPoints(user.id),  // this can call another service!  },  OrderItem: {    product: (item) => db.products.findById(item.productId),  },};

The GraphQL engine reads the query and calls the resolvers it needs. A resolver can get data from a database, a REST API, a gRPC service or a cache. GraphQL is a layer in front of your data sources. It is not a database.

The N+1 problem (again!)

The N+1 problem means running one query to get a list, then one more query for each item in the list. For N items that is N+1 queries, which is slow.

Look at OrderItem.product above. If the query returns 3 orders with 4 items each, that resolver runs 12 times, which is 12 separate database queries. This is the same N+1 problem as in lesson 5, and it is easy to create by accident in GraphQL.

The fix: DataLoader. DataLoader is a small library that batches (groups) many small lookups into one. It also caches results for the length of one request. It collects all the product IDs asked for during one tick (one turn of the JavaScript event loop), then fetches them in one query:

// One query for all ids. The function must return the results in the same order as the ids.const productLoader = new DataLoader(ids => db.products.findByIds(ids));OrderItem: {  product: (item) => productLoader.load(item.productId),}

Twelve queries became 1. Almost every serious GraphQL server uses this pattern.

The caching challenge

REST GETs are easy to cache. Each URL is a resource, and CDNs (networks that keep copies of content near users) understand Cache-Control (lesson 14). GraphQL usually sends POST requests to one URL with different queries in the body, so HTTP and CDN caching does not work by default.

Solutions:

• Persisted queries: the server stores approved queries in advance. The client sends only a hash or ID of the query (a hash is a short fingerprint), and it can use GET. This makes responses cacheable and also blocks queries that nobody approved.
• Client-side normalised caches (Apollo Client, Relay) store each object once, under its ID, so the same User:42 is reused on every screen.
• Server-side caching in resolvers or DataLoaders, plus Redis, a fast in-memory cache (lessons 15–16).

Security and performance risks

Because clients can write any query, a harmful or careless client can send a huge one. This example goes deeper and deeper through friends of friends:

{ user(id: "1") { friends { friends { friends { friends { name } } } } } }

Protections:

• Query depth limits: refuse queries that nest too deep, for example more than 7 levels.
• Query cost analysis: give each field a cost and reject queries whose total is over a budget.
• Pagination required on lists (lesson 34).
• Timeouts and rate limits based on query cost, not just request count.
• Persisted queries only for your own apps (no arbitrary queries in production).
• Authorisation in resolvers. Authorisation means checking what a user may see or do. Check it for each field and object, not only at the endpoint.
• Consider turning off introspection in production for private APIs. Introspection lets any client ask the server to describe its whole schema.

Errors are different

GraphQL often returns HTTP 200 even when parts of the query fail, with an errors array next to partial data. This is useful, because you still get the parts that worked. But monitoring tools that only look at HTTP status codes will miss these failures. Track GraphQL errors on purpose.

Federation: one graph, many teams

In large companies, many teams own different parts of the data. GraphQL Federation (for example, Apollo Federation) lets each team run its own subgraph (a small GraphQL API for users, orders or products). A gateway (also called a router) then combines them into one unified schema for clients:

When to use which

Many companies use all three: REST for public APIs, GraphQL for their own apps, and gRPC between services.