REST and GraphQL, Conceptually

Build the mental model

REST is an API style built around resources identified by URLs and manipulated through HTTP methods.

GET /users - list users
GET /users/42 - fetch one user
POST /users - create a user
PATCH /users/42 - update a user
DELETE /users/42 - delete a user

GraphQL typically exposes one endpoint, and the client sends a query naming the fields it wants, for example { user(id: 42) { name, avatarUrl } }.

Aspect	REST vs GraphQL
Endpoint shape	REST: many endpoints, one per resource. GraphQL: typically a single endpoint for all queries.
Data selection	REST: server decides response shape per endpoint. GraphQL: client selects exactly which fields it wants.
Caching	REST: benefits from mature HTTP-level caching. GraphQL: usually needs custom, application-level caching.
Complexity	REST: simpler infrastructure, more endpoints to maintain. GraphQL: single schema to maintain, more upfront query-cost complexity.
Good fit for	REST: simple, resource-shaped APIs and heavy caching needs. GraphQL: complex clients needing flexible, precise data fetching.

text

REST VS GRAPHQL SHAPE
---------------------
REST: MULTIPLE ENDPOINTS         GRAPHQL: ONE ENDPOINT
-------------------------         -----------------------

 Client                            Client
   |-- GET /users/42 --> Server      |-- POST /graphql --> Server
   |-- GET /users/42                 |   { user(id:42){
   |     /avatar --------> Server    |     name, avatarUrl } }
   |                                 |<-- { name, avatarUrl }
  (2 requests, fixed shape)         (1 request, chosen shape)

Connect it to a real scenario

If a page needs only name and avatarUrl, REST may need two calls while GraphQL can do it in one query.

In the code below, fetchViaRest and fetchViaGraphql run against the same mock data and produce an identically-shaped result.

REST exposes multiple resource-shaped endpoints; GraphQL typically exposes one endpoint and lets the client pick fields.
Neither approach is automatically better or faster - REST leans on mature HTTP caching, GraphQL trades that for flexible field selection.
The full depth of REST methods, status codes, and API design lives in the API Tutorial and API Integration & Webhooks course.

Try the working example

javascript

// Mock "server-side" data
const usersDb = {
  42: { id: 42, name: "Dana", avatarUrl: "https://cdn.example.com/dana.png", email: "dana@example.com" },
};

// REST-style: separate endpoint calls
function restGetUser(id) {
  return { ...usersDb[id] }; // GET /users/:id returns the full record
}
function restGetAvatar(id) {
  return { avatarUrl: usersDb[id].avatarUrl }; // GET /users/:id/avatar
}

function fetchViaRest(id) {
  const user = restGetUser(id);
  const avatar = restGetAvatar(id);
  return { name: user.name, avatarUrl: avatar.avatarUrl };
}

// GraphQL-style: one call, client picks fields
function graphqlQuery(id, fields) {
  const record = usersDb[id];
  const result = {};
  fields.forEach((field) => {
    result[field] = record[field];
  });
  return result;
}

function fetchViaGraphql(id) {
  return graphqlQuery(id, ["name", "avatarUrl"]);
}

console.log("REST result:", fetchViaRest(42));
console.log("GraphQL result:", fetchViaGraphql(42));

You should see

Both fetchViaRest(42) and fetchViaGraphql(42) log the identical result: { name: 'Dana', avatarUrl: 'https://cdn.example.com/dana.png' }.

5-minute try-it

Add an 'email' field to the mock user and extend fetchViaGraphql to request it, then compare how much code changes versus adding an equivalent REST endpoint call.

One important caution

Claiming GraphQL is always faster or better than REST - the right choice depends on caching needs, client variety, and team familiarity.

Treating this lesson's endpoint list as the complete picture of REST - the full method and status semantics live in the API Tutorial.

GraphQL.org - Introduction to GraphQL — How the Web Works