JS-230 · Lesson 8 of 12 · 34 min
Building a REST API
▶ Video coming soon A video version of this lesson is on the way.
On Thursday, March 30, Mira and Theo sit down with the list of routes she wrote in Lesson 4 and the contract Theo wrote for his own API a year earlier, when the dashboard was being built. "The agencies' developers will read your API the way you read mine," Theo says. "If it behaves like every other good API, they will guess right most of the time. Same rules for methods, same status codes, same pagination, same error format." Gareth adds the hard cases: what happens when a request is sent twice, and when two people change the same order.
This lesson turns the service's routes into a complete REST API. It explains the ideas behind REST: resources, representations and the meaning of each HTTP method, including which methods are safe and which are idempotent. It designs the order resource's JSON, lists orders with filters and cursor pagination like Theo's API, makes order creation safe to retry with an Idempotency-Key, changes orders with PATCH, protects against lost updates with ETags, and withdraws orders with DELETE. It ends with an OpenAPI description that the agencies' developers can read. By the end, every operation on Rosa's list has a route that behaves predictably.
Resources and representations
REST, short for representational state transfer, is a style of API design described by Roy Fielding in 2000, and today the word mostly means "an HTTP API that uses HTTP the way it was designed". Its central idea is the resource: a thing the API exposes, such as an order or the menu, identified by a URL. Clients never touch resources directly; they exchange representations of them, usually JSON documents, and use the HTTP methods to say what they want done.
Good resource URLs are nouns, not verbs: /orders and /orders/17, not /createOrder or /getOrderById?id=17. The method says what to do. Collections are plural, and an item is the collection's URL plus an id. Filters, sorting and pages belong in the query string, because they choose which representations to return rather than naming a different resource.
| Request | Meaning | Success |
|---|---|---|
| GET /orders?from=2028-04-03&to=2028-04-07 | List this agency's orders in a date range | 200 with items and next |
| POST /orders | Place a new order | 201 with Location |
| GET /orders/17 | Read one order | 200 with an ETag |
| PATCH /orders/17 | Change some fields of an order | 200 with the new order |
| DELETE /orders/17 | Withdraw an order | 204 with no body |
| GET /menu | What the kitchen offers | 200 |
| GET /kitchen/days/2028-04-05 | Rosa's day sheet (kitchen role) | 200 |
What the methods promise
HTTP defines what each method means, and clients, browsers, caches and proxies rely on those meanings. A safe method does not change anything on the server: GET and HEAD are safe, so a cache may store their responses and a browser may fetch them ahead of time. An idempotent method has the same effect whether it is sent once or several times: GET, PUT and DELETE are idempotent, so a client whose connection dropped can simply send them again. POST and PATCH are neither, which is why they need extra care.
| Method | Safe | Idempotent | Typical use |
|---|---|---|---|
| GET | Yes | Yes | Read a resource or a list |
| POST | No | No | Create a resource in a collection, or run an action |
| PUT | No | Yes | Replace a resource completely |
| PATCH | No | No (can be made so) | Change part of a resource |
| DELETE | No | Yes | Remove a resource |
Idempotent does not mean the response is always the same. The first DELETE /orders/17 withdraws the order and the second finds it already withdrawn, but the order's state after both is the same, and the service answers 204 both times. What matters is that repeating the request does no further harm. The partner service never uses GET to change anything, so a link that a browser prefetches or a crawler follows can never withdraw an order.
The order representation
The JSON for an order is designed for the agencies, not copied from the database row. It uses camelCase names like the rest of the studio's JavaScript, dates as YYYY-MM-DD strings and times as ISO strings with a time zone, and it leaves out what the agencies do not need: the internal partner_id, the idempotency key and the stored hash of anything. It includes a link to itself, so a client never has to build URLs by hand.
{
"id": 17,
"deliveryDate": "2028-04-05",
"status": "received",
"lines": [
{ "item": "soup", "trays": 4 },
{ "item": "sandwiches", "trays": 2 }
],
"note": "Side door, please",
"updatedAt": "2028-03-30T14:12:09.000Z",
"links": { "self": "/api/partners/v1/orders/17" }
}What this code does
Every field has a stable name and a predictable type, so the agencies' programs can rely on it. status tells the agency whether the order is still received, withdrawn or delivered, and updatedAt says when it last changed. The self link means a client can follow the URL it was given rather than putting paths together itself.
Lists, filters and pages
An agency that has ordered three times a week for two years has over 300 orders. Returning them all in one response would be slow and mostly useless, so the list is returned in pages. Theo's API uses cursor pagination: each response contains a page of items and, if there are more, a next value that the client sends back to get the following page. The partner API does the same, so the agencies' developers and Mira's own front-end code can use one approach for both.
The alternative, offset pagination with ?page=3 or ?offset=40, is simpler but has two problems. If an order is added or withdrawn while a client is paging, items shift between pages, so some are seen twice and some are missed. And the database must count past all the skipped rows for every page, which gets slower as the offset grows. A cursor records where the last page ended, for example the last order's delivery date and id, and the next query starts after that point, which is both stable and fast with an index.
const toCursor = (o) => btoa(JSON.stringify([o.deliveryDate, o.id])).replaceAll('=', '');
const fromCursor = (c) => JSON.parse(atob(c));
function page(all, { limit = 2, after } = {}) {
const sorted = [...all].sort((a, b) => a.deliveryDate.localeCompare(b.deliveryDate) || a.id - b.id);
let start = 0;
if (after) {
const [date, id] = fromCursor(after);
start = sorted.findIndex((o) => o.deliveryDate > date || (o.deliveryDate === date && o.id > id));
if (start === -1) start = sorted.length;
}
const items = sorted.slice(start, start + limit);
const more = start + limit < sorted.length;
return { items: items.map((o) => o.id), next: more ? toCursor(items.at(-1)) : null };
}
const orders = [
{ id: 17, deliveryDate: '2028-04-05' }, { id: 12, deliveryDate: '2028-04-03' },
{ id: 21, deliveryDate: '2028-04-05' }, { id: 25, deliveryDate: '2028-04-07' },
{ id: 14, deliveryDate: '2028-04-03' },
];
let p = page(orders);
console.log(p);
orders.push({ id: 30, deliveryDate: '2028-04-03' }); // a new order arrives between pages
p = page(orders, { after: p.next });
console.log(p);
p = page(orders, { after: p.next });
console.log(p);{ items: [ 12, 14 ], next: "WyIyMDI4LTA0LTAzIiwxNF0" }
{ items: [ 30, 17 ], next: "WyIyMDI4LTA0LTA1IiwxN10" }
{ items: [ 21, 25 ], next: null }What this code does
page sorts by delivery date and then id, so the order is always the same, and the cursor is the last item's date and id, encoded as text with btoa. The next page starts at the first item after that point, wherever it is now, so the order added between pages cannot push an item onto the wrong page or show one twice. The last page returns next: null, which tells the client to stop.
A cursor is opaque to clients: they must send it back unchanged and must not try to read or build it, which leaves the service free to change what is inside. The list also takes a limit, with a sensible default of 25 and a maximum of 100, so no client can ask for everything at once. In SQL, the page query compares the pair (delivery_date, id) with the pair stored in the cursor, sorts by the same two columns and asks for one row more than the limit, so the extra row shows whether there is a next page.
Creating safely: idempotency keys
POST is not idempotent, and that causes a real problem. A coordinator at Northside presses Place order on a bad connection. The request reaches the service and the order is saved, but the response is lost on the way back. The form, or the coordinator, tries again, and the kitchen now has two orders. Theo's counter API solved this with an Idempotency-Key header, and the partner API requires it on every POST: the client creates a random key for each new order, and sends the same key if it retries.
The service stores each key with the agency and the response it produced. A request with a new key is processed normally. A request with a key it has seen before is not processed again; the service sends back the stored response. If the same key arrives with a different body, that is a client bug, and the service answers 422 rather than guessing which order was meant. Keys are kept for 24 hours, long enough for any sensible retry. The unique constraint on partner_id and idempotency_key in Lesson 7's table makes sure that even two retries arriving at the same moment cannot both create an order.
function createIdempotencyStore() {
const seen = new Map(); // `${partner}:${key}` -> { bodyText, response }
let nextId = 40;
return function post(partner, key, body) {
if (!key) return { status: 400, body: { title: 'Idempotency-Key header is required' } };
const id = `${partner}:${key}`;
const bodyText = JSON.stringify(body);
const earlier = seen.get(id);
if (earlier) {
if (earlier.bodyText !== bodyText) return { status: 422, body: { title: 'This key was used for a different order' } };
return { ...earlier.response, replayed: true };
}
const response = { status: 201, body: { id: nextId++, ...body } };
seen.set(id, { bodyText, response });
return response;
};
}
const post = createIdempotencyStore();
const order = { deliveryDate: '2028-04-05', lines: [{ item: 'soup', trays: 4 }] };
console.log(post('northside', 'b7e1-4c2a', order)); // first attempt: response lost
console.log(post('northside', 'b7e1-4c2a', order)); // retry with the same key
console.log(post('northside', 'b7e1-4c2a', { ...order, lines: [{ item: 'stew', trays: 4 }] }));
console.log(post('elm-seniors', 'b7e1-4c2a', order)); // same key, different agency
console.log(post('northside', undefined, order));{ status: 201, body: { id: 40, deliveryDate: "2028-04-05", lines: [ { item: "soup", trays: 4 } ] } }
{ status: 201, body: { id: 40, deliveryDate: "2028-04-05", lines: [ { item: "soup", trays: 4 } ] }, replayed: true }
{ status: 422, body: { title: "This key was used for a different order" } }
{ status: 201, body: { id: 41, deliveryDate: "2028-04-05", lines: [ { item: "soup", trays: 4 } ] } }
{ status: 400, body: { title: "Idempotency-Key header is required" } }What this code does
The store remembers each key per agency with the body and the response it gave. A retry with the same key and body gets the stored 201 back, marked replayed, and no second order is created. The same key with a different body is refused with 422, a different agency's identical key is unrelated and creates its own order, and a POST without a key is refused before anything happens.
Changing an order: PATCH
Agencies often change an order before the cut-off: one more tray of soup, no sandwiches this week, a different note. PATCH sends only the parts that change. The partner API uses the simple JSON Merge Patch format (RFC 7396): the body is an object whose properties replace the order's properties, and a property set to null is removed. The lines are replaced as a whole list, because merging lists item by item is confusing. After merging, the result goes through the same checks as a new order, including the cut-off and capacity rules.
function mergePatch(target, patch) {
if (patch === null || typeof patch !== 'object' || Array.isArray(patch)) return patch;
const result = (target && typeof target === 'object' && !Array.isArray(target)) ? { ...target } : {};
for (const [key, value] of Object.entries(patch)) {
if (value === null) delete result[key];
else result[key] = mergePatch(result[key], value);
}
return result;
}
const order = { deliveryDate: '2028-04-05', lines: [{ item: 'soup', trays: 4 }, { item: 'sandwiches', trays: 2 }], note: 'Side door, please' };
console.log(mergePatch(order, { lines: [{ item: 'soup', trays: 5 }] }));
console.log(mergePatch(order, { note: null }));
console.log(mergePatch(order, { deliveryDate: '2028-04-07', note: 'Front desk' }));
console.log('original unchanged:', order.lines.length, order.note);{ deliveryDate: "2028-04-05", lines: [ { item: "soup", trays: 5 } ], note: "Side door, please" }
{ deliveryDate: "2028-04-05", lines: [ { item: "soup", trays: 4 }, { item: "sandwiches", trays: 2 } ] }
{ deliveryDate: "2028-04-07", lines: [ { item: "soup", trays: 4 }, { item: "sandwiches", trays: 2 } ], note: "Front desk" }
original unchanged: 2 Side door, pleaseWhat this code does
mergePatch copies the target and then applies each property of the patch: null deletes the property, objects are merged one level deeper and anything else, including arrays, replaces the old value. Replacing the whole lines list means the first patch leaves only the soup line, exactly what the agency sent. The original order object is never changed, so the service can still compare old and new versions.
Changing the delivery date is allowed if both the old date and the new one are before their cut-offs, because moving an order takes trays from one day and adds them to another. The repository's update locks both days' rows, in date order so that two updates moving orders in opposite directions cannot wait for each other forever.
Lost updates and ETags
Westview has two staff members who order food. On Monday, Priya opens Wednesday's order to add a tray of stew, and Sam opens the same order to change the note. Sam saves first. Priya, whose screen still shows the old order, then saves the whole order with her new line and the old note, and Sam's change is silently lost. This is a lost update, and the standard HTTP answer is optimistic concurrency with ETags.
Each order has a version number that goes up with every change. The service sends it in an ETag header with every GET. When a client sends a PATCH, it includes the ETag it last saw in an If-Match header. If the order has changed since, the versions differ, and the service refuses with 412 Precondition Failed, so the client can load the order again, show the person what changed and let them apply their change on top. Nobody's work is lost without warning.
let stored = { id: 31, version: 4, lines: [{ item: 'soup', trays: 3 }], note: 'Front desk' };
function patch(ifMatch, changes) {
if (ifMatch !== `"${stored.version}"`) return { status: 412, title: 'The order has changed', current: `"${stored.version}"` };
stored = { ...stored, ...changes, version: stored.version + 1 };
return { status: 200, etag: `"${stored.version}"` };
}
const priyaSaw = '"4"';
const samSaw = '"4"';
console.log('Sam: ', patch(samSaw, { note: 'Use the side door' }));
console.log('Priya:', patch(priyaSaw, { lines: [{ item: 'soup', trays: 3 }, { item: 'stew', trays: 1 }] }));
console.log('Priya reloads and tries again:', patch(`"${stored.version}"`, { lines: [{ item: 'soup', trays: 3 }, { item: 'stew', trays: 1 }] }));
console.log(stored);Sam: { status: 200, etag: "\"5\"" }
Priya: { status: 412, title: "The order has changed", current: "\"5\"" }
Priya reloads and tries again: { status: 200, etag: "\"6\"" }
{ id: 31, version: 6, lines: [ { item: "soup", trays: 3 }, { item: "stew", trays: 1 } ], note: "Use the side door" }What this code does
Both staff members load version 4. Sam's patch matches, so it is applied and the version becomes 5. Priya's patch still says version 4, so the service answers 412 with the current version instead of overwriting Sam's note; after reloading, her patch carries version 5 and succeeds, and the stored order keeps both changes.
If-Match is optional in the partner API, so simple clients still work, but the partners' web form always sends it. ETags have a second use with GET: a client can send If-None-Match with the ETag it has, and if nothing changed the server answers 304 Not Modified with no body, saving bandwidth. Express adds weak ETags to GET responses automatically; the service sets its own, based on the version, so they match what PATCH checks.
Withdrawing an order
Agencies sometimes need to withdraw an order, for example when a shelter's dinner is cancelled by its own partner. DELETE /orders/17 changes the order's status to withdrawn rather than removing the row: Rosa wants a record of what was ordered and withdrawn, and the agencies can still see it in their list. It answers 204 No Content, which means success with no body. Withdrawing an already withdrawn order also answers 204, keeping DELETE idempotent, and withdrawing after the cut-off answers 409, because by then the kitchen has started cooking.
The routes together
// src/routes/orders.js
import { Router } from 'express';
import * as z from 'zod';
import { validate } from '../middleware/validate.js';
import { idempotent } from '../middleware/idempotent.js';
import { NewOrder, OrderPatch, ListQuery } from '../schemas.js';
import { HttpError } from '../errors.js';
import * as orders from '../orders-repo.js';
export const ordersRouter = Router();
const Id = z.coerce.number().int().positive();
function present(order, baseUrl) {
return { id: order.id, deliveryDate: order.deliveryDate, status: order.status, lines: order.lines,
note: order.note ?? null, updatedAt: order.updatedAt, links: { self: `${baseUrl}/${order.id}` } };
}
async function load(req) {
const id = Id.safeParse(req.params.id);
const order = id.success ? await orders.get(req.partner.id, id.data) : null;
if (!order) throw new HttpError(404, 'Not found', 'No such order for this agency');
return order;
}
ordersRouter.get('/', validate(ListQuery, 'query'), async (req, res) => {
const page = await orders.listForPartner(req.partner.id, req.valid.query);
res.json({ items: page.items.map((o) => present(o, req.baseUrl)), next: page.next });
});
ordersRouter.post('/', idempotent, validate(NewOrder), async (req, res) => {
const order = await orders.create(req.partner.id, req.body, req.get('Idempotency-Key'));
res.status(201).location(`${req.baseUrl}/${order.id}`).json(present(order, req.baseUrl));
});
ordersRouter.get('/:id', async (req, res) => {
const order = await load(req);
res.set('ETag', `"${order.version}"`).json(present(order, req.baseUrl));
});
ordersRouter.patch('/:id', validate(OrderPatch), async (req, res) => {
const order = await load(req);
const ifMatch = req.get('If-Match');
if (ifMatch && ifMatch !== `"${order.version}"`) {
throw new HttpError(412, 'The order has changed', 'Load it again and reapply your change');
}
const updated = await orders.update(req.partner.id, order, req.body); // checks cut-off and capacity
res.set('ETag', `"${updated.version}"`).json(present(updated, req.baseUrl));
});
ordersRouter.delete('/:id', async (req, res) => {
const order = await load(req);
if (order.status === 'received') await orders.withdraw(req.partner.id, order); // checks cut-off
res.sendStatus(204);
});What this code does
present turns a stored order into the public representation with its self link, and load finds an order that belongs to the calling agency or throws a 404, so no route can reach another agency's orders. Validation runs before every handler that reads input, POST requires an idempotency key, GET sends the version as an ETag and PATCH refuses with 412 if If-Match no longer matches. Rule checks such as the cut-off and capacity live in the repository functions, which throw RuleErrors that the error handler from Lesson 6 turns into 409 responses.
Every handler is short because the hard work is elsewhere: middleware identifies the agency, validates the input and handles idempotency; the repository applies the rules and talks to the database; the error handler formats every failure. Each handler only connects these pieces and chooses the status code, which makes the routes easy to review against the table at the start of the lesson.
Describing the API
The agencies' developers need documentation, and a description that machines can read is even better. OpenAPI is a standard format, written in YAML or JSON, that lists an API's paths, methods, parameters, request bodies, responses and schemas. Tools turn it into readable reference pages, generate client code and check that responses match. Mira writes the description by hand for version 1; zod schemas can also be converted to the JSON Schema that OpenAPI uses, which keeps the two in step.
openapi: 3.1.0
info:
title: Riverside partner orders
version: 1.0.0
servers:
- url: https://partners.riverside-food-hub.example/api/partners/v1
paths:
/orders:
post:
summary: Place an order
parameters:
- { name: Idempotency-Key, in: header, required: true, schema: { type: string, maxLength: 100 } }
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/NewOrder' }
responses:
'201': { description: Order placed, headers: { Location: { schema: { type: string } } } }
'409': { description: Cut-off passed or not enough capacity, content: { application/problem+json: {} } }
'422': { description: Invalid values, content: { application/problem+json: {} } }What this code does
The file starts with the API's title, version and base URL, then describes each path and method. This extract shows the POST on /orders with its required Idempotency-Key header, its JSON body, which refers to a schema defined later in the file, and the responses it can give. A documentation tool turns the full file into a reference page for the agencies.
Version 1 in the path is a promise: the representation and behaviour of /api/partners/v1 will not change in ways that break existing clients. New optional fields can be added, because clients should ignore fields they do not know, but removing or renaming a field, or changing a status code, would need a /v2 beside it, with version 1 kept running until every agency has moved.
Worked problem
How many requests does a full list take?
Northside has 312 orders. Its developer wants all of them for a yearly report and uses the default limit of 25, then tries the maximum of 100. How many requests does each take, and how many orders are on the last page?
Show solution
- With 25 per page: 312 ÷ 25 = 12.48, so 13 requests; the last page has 312 − 12 × 25 = 12 orders.
- With 100 per page: 312 ÷ 100 = 3.12, so 4 requests; the last page has 312 − 3 × 100 = 12 orders.
- Each response except the last includes a next cursor; the last returns next: null.
Answer: 13 requests at the default limit or 4 at the maximum, with 12 orders on the last page either way. The developer follows next until it is null and never needs to know the total in advance.
Common mistakes
MistakeA GET request that changes data is fine if the client means it.
InsteadGET must be safe. Prefetching, caches and crawlers send GETs without asking anyone.
MistakeRetrying a POST is harmless.
InsteadIt can create a second order. Use an Idempotency-Key so a retry returns the first response.
MistakeOffset pagination with ?page=3 is just as good as a cursor.
InsteadItems shift between pages when data changes, and large offsets are slow. A cursor is stable.
MistakeThe last request to save an order should simply win.
InsteadThat loses the other person's change. Use ETags with If-Match and answer 412 when the order has changed.
Summary and key terms
- A REST API exposes resources at noun URLs and uses the HTTP methods for what they mean: GET reads and is safe, POST creates, PATCH changes part of a resource, PUT replaces it and DELETE removes it; GET, PUT and DELETE are idempotent.
- Representations are designed for clients, with stable field names, standard formats and self links, and leave out internal details.
- Lists use filters in the query string and opaque cursors for pages, which stay correct when data changes and are fast with an index.
- An Idempotency-Key on POST lets a client retry without creating a duplicate.
- PATCH uses JSON Merge Patch and the same rule checks as creation.
- ETags with If-Match prevent lost updates by answering 412 when a resource has changed.
- DELETE withdraws an order with 204.
- An OpenAPI description documents the API, and the version in the path is a promise not to break existing clients.
- REST
- A style of API design built on resources, representations and the standard meaning of HTTP methods.
- Resource
- A thing an API exposes, such as an order, identified by a URL.
- Representation
- A document, usually JSON, that describes the current state of a resource.
- Safe method
- A method that does not change anything on the server, such as GET.
- Idempotent
- Having the same effect whether a request is sent once or several times.
- Cursor pagination
- Returning a list in pages, with an opaque value that marks where the next page starts.
- Idempotency-Key
- A request header with a client-chosen key that lets a server recognize and replay a retried request.
- JSON Merge Patch
- A format for PATCH bodies in which properties replace old values and null removes them.
- ETag
- A response header identifying a version of a resource.
- 412 Precondition Failed
- The response when an If-Match header does not match the current version.
- OpenAPI
- A standard, machine-readable format for describing an HTTP API.
Practice problems
Work each problem on paper first, then reveal the answer to check.
Why should a URL be /orders/17 rather than /getOrder?id=17?
Show answer
Resources are nouns; the method says what to do.
Which of GET, POST, PATCH and DELETE are idempotent?
Show answer
GET and DELETE.
Why does a cursor stay correct when a new order is added between pages?
Show answer
It records where the last page ended, so the next page starts after that point, wherever the items have moved.
What does the service do when a POST arrives with a key it has already seen and the same body?
Show answer
It sends the stored response again without creating another order.
When does the service answer 412?
Show answer
When a PATCH's If-Match header does not match the order's current version.
Try it yourself
Paginate a list
Complete paginate(items, limit, after). items is already sorted by id. Return { items, next }, where items holds at most limit entries whose id is greater than after (or from the start if after is null), and next is the id of the last returned item if more items follow, or null if not.
The example uses plain ids as cursors to keep it simple; a real API would encode them.
function paginate(items, limit, after) {
return { items: items.slice(0, limit), next: null };
}
const all = [3, 5, 8, 9, 12, 15, 21].map((id) => ({ id }));
let cursor = null;
do {
const page = paginate(all, 3, cursor);
console.log(page.items.map((i) => i.id).join(','), '-> next', page.next);
cursor = page.next;
} while (cursor !== null);
console.log(paginate(all, 3, 21));Try it yourself
Apply an order patch
Complete applyPatch(order, patch). It returns a new order with the patch applied as a JSON Merge Patch: each property in patch replaces the order's property, and null removes it. Only deliveryDate, lines and note may be patched.
If the patch contains any other property, return the string cannot change FIELD for the first such property instead. The original order must not change.
function applyPatch(order, patch) {
return Object.assign(order, patch);
}
const order = { id: 17, status: 'received', deliveryDate: '2028-04-05', lines: [{ item: 'soup', trays: 4 }], note: 'Side door' };
console.log(applyPatch(order, { lines: [{ item: 'soup', trays: 5 }], note: null }));
console.log(applyPatch(order, { deliveryDate: '2028-04-07' }));
console.log(applyPatch(order, { status: 'delivered' }));
console.log(order.note, order.lines[0].trays, order.status);Lesson quiz · 5 questions
Score 60% or more to complete this lesson.
Create a free account to save your progress, take quizzes and earn a certificate.