Backend Development8 min read

How to Structure a REST API That Scales

Resource naming, versioning, pagination, error shapes and idempotency: the conventions that keep a REST API maintainable as it grows.

UL

Ullass Engineering Team

Editorial Team — Software Development & Digital Products

What REST Actually Commits You To

REST was described by Roy Fielding in 2000 as an architectural style, not a protocol. The summary most people carry — nouns in the URL, verbs in the method, JSON in the body — covers maybe half of it. The constraint teams forget is the uniform interface: every resource has a stable identifier, and what you return is a representation rather than a window onto your storage. That is why an API survives a database rewrite.

The second half is the part almost nobody implements. Fielding's original formulation leans on hypermedia: responses advertise the available transitions so a client discovers them at runtime. In commercial APIs that has largely been abandoned, which is why you can find thousands of healthy REST services that ignore it. Treat hypermedia as off the table and pay the tax honestly — a REST API you design for people and third-party SDKs is verbose, and it is verbose on purpose.

Everything below follows the current HTTP semantics as documented in MDN's HTTP method reference, which is the most readable statement of what each verb obliges you to do.

Resource Naming and the Shape of a URL

Resources are nouns, plural, and identified by a path. The method carries the action.

http
GET /v1/orders POST /v1/orders GET /v1/orders/4521 PUT /v1/orders/4521 PATCH /v1/orders/4521 DELETE /v1/orders/4521

The distinction between PUT and PATCH trips up nearly every new integration. PUT replaces the resource: omit a field and it goes back to its default, and sending the same body twice produces the same state. PATCH applies a partial update: omit a field and it is untouched. If a client can send the same PUT twice without changing the result, the endpoint is idempotent by construction — which is exactly why PUT and DELETE are safe to retry and POST is not.

Plural collection paths with singular identifiers (/orders/4521) scale better than the reverse because /orders/search stays unambiguous once you have sub-resources. Nest at most one level deep:

http
GET /v1/orders/4521/line-items

Past that depth, nesting encodes a hierarchy the data does not have, and you inherit the problem of moving an order between customers without moving its children. Use a filter on the top-level collection instead — GET /v1/line-items?order_id=4521 — and stop pretending the two resources are nested.

One Response Envelope, One Error Shape

The highest-leverage decision you will make is that every endpoint returns the same envelope, so a client SDK needs one code path for success and one for failure.

json
{ "data": { "id": "4521", "status": "paid", "total_cents": 12900, "currency": "GBP", "created_at": "2025-08-25T09:14:02Z" }, "meta": { "request_id": "req_8fJ2p0mQ" } }

Money as an integer number of minor units plus a currency code is not a style preference — binary floating point cannot represent 19.99 exactly, and a ledger built on floats will not reconcile. Same for timestamps: ISO 8601 in UTC, always.

Errors carry a machine-readable code, a human-readable message, and the request id so a user can quote it in support:

json
{ "error": { "code": "order_already_paid", "message": "Order 4521 was paid at 09:14:02Z and cannot be modified.", "request_id": "req_8fJ2p0mQ", "docs": "https://api.example.com/docs/errors/order-already-paid" } }
ts
// lib/errors.ts export class ApiError extends Error { constructor( readonly status: number, readonly code: string, message: string, ) { super(message); this.name = "ApiError"; } static badRequest(code: string, message: string) { return new ApiError(400, code, message); } static unprocessable(code: string, message: string) { return new ApiError(422, code, message); } static conflict(code: string, message: string) { return new ApiError(409, code, message); } } // lib/http.ts import { NextResponse } from "next/server"; export function errorResponse(err: unknown, requestId: string) { if (err instanceof ApiError) { return NextResponse.json( { error: { code: err.code, message: err.message, request_id: requestId } }, { status: err.status }, ); } // Anything unrecognised becomes a 500 with no internals leaked to the client. console.error("unhandled", { requestId, err }); return NextResponse.json( { error: { code: "internal_error", message: "Something went wrong.", request_id: requestId } }, { status: 500 }, ); }

Note the deliberate asymmetry: log the detail, return the summary. An error message that echoes a Postgres constraint name or a stack frame hands an attacker a schema for free.

Validation errors clients can act on

A 400 that says "invalid request" is useless to the caller. Point them at the field:

json
{ "error": { "code": "validation_failed", "message": "Request body failed validation.", "details": [ { "field": "items[0].quantity", "issue": "must be an integer between 1 and 99" }, { "field": "currency", "issue": "must be a supported ISO 4217 code" } ], "request_id": "req_8fJ2p0mQ" } }

Use 422 for a body that is syntactically valid JSON but semantically wrong, and 400 for a body that could not be parsed at all. That distinction lets a client decide whether to retry, and it follows the semantics RFC 9110 defines for status codes.

Versioning: Three Strategies and How to Retire One

Versioning is not the hard part. Admitting that a change is breaking, and telling consumers when you are removing the old one, is the hard part. There are three honest options:

  1. URL versioning (/v1/orders). Blazing obvious in logs, trivial to route, trivial to test, and it leaks into every client config. This is the default for a public API.
  2. Header versioning (Accept: application/vnd.example.v2+json). Keeps URLs clean, but nothing in a plain browser or curl will tell you the version was ever there, and misconfigured clients fail silently.
  3. Content negotiation on the media-type parameter, which is the standard-blessed form of option two.

Whichever you pick, keep the rule that a version only ever grows. Clients in the wild do not upgrade when you tell them to — they upgrade when they have to, during someone else's maintenance window.

For additive changes you do not need a version at all: new optional response fields, new enum members on the write path, new endpoints. Reserve versions for removals, renames and semantic changes. Then publish a machine-readable deprecation header on every response from a version you intend to remove, and give it a published end-of-life date:

http
HTTP/1.1 200 OK Deprecation: @1767225600 Sunset: Sat, 02 Jan 2027 00:00:00 GMT Link: <https://api.example.com/docs/migrations/v2>; rel="deprecation"

That Sunset header is specified in RFC 8594 and is supported by the same tooling that reads ETag, so your existing monitors can alert on it without new code.

Pagination That Survives Concurrent Writes

LIMIT/OFFSET is the obvious choice and the wrong one for anything that changes underneath the reader. With OFFSET 100, if 12 rows are deleted before page two is fetched, row 101 silently appears twice and one row is never returned. OFFSET 100000 also makes the database walk 100,000 rows to discard them.

Keyset pagination fixes both. Sort by a unique, monotonic column, carry the last seen value as an opaque cursor, and inserts and deletes elsewhere in the table simply cannot shift your window:

ts
// GET /v1/orders?limit=50&cursor=eyJjcmVhdGVkQXQiOiIyMDI1LTA4LTI1VDA5OjE0OjAwOjAwWiIsImlkIjoiNDUyMSJ9 type Order = { id: string; created_at: string; status: string; total_cents: number; }; const encodeCursor = (row: Pick<Order, "created_at" | "id">) => Buffer.from(JSON.stringify({ createdAt: row.created_at, id: row.id })).toString("base64url"); const decodeCursor = (cursor: string) => { try { const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")); if (typeof parsed.createdAt !== "string" || typeof parsed.id !== "string") { throw new Error("unexpected cursor shape"); } return parsed as { createdAt: string; id: string }; } catch { throw ApiError.badRequest("invalid_cursor", "Cursor is not readable."); } }; export async function listOrders(req: Request) { const url = new URL(req.url); const limit = Math.min(Number(url.searchParams.get("limit") ?? 25), 100); const cursor = url.searchParams.get("cursor"); let sql = "SELECT id, created_at, status, total_cents FROM orders"; const values: unknown[] = []; if (cursor) { const { createdAt, id } = decodeCursor(cursor); values.push(createdAt, id); sql += " WHERE (created_at, id) < ($" + values.length + "::timestamptz, $" + values.length + ")"; } values.push(limit + 1); sql += " ORDER BY created_at DESC, id DESC LIMIT $" + values.length; const { rows } = await pool.query<Order>(sql, values); // One extra row tells us whether a next page exists, without a COUNT(). const hasMore = rows.length > limit; const page = hasMore ? rows.slice(0, limit) : rows; return { data: page, pagination: { next_cursor: hasMore ? encodeCursor(page[page.length - 1]) : null, per_page: limit, }, }; }

Fetching limit + 1 rows rather than running a COUNT(*) is the difference between one index scan and a second full pass over the table on every page — on a 40M-row orders table that is the difference between 3ms and 900ms.

That composite (created_at, id) sort is the part worth copying: a timestamp alone is not unique, and rows sharing one produce duplicate-or-skipped pages that look exactly like data loss.

What the client should do with the response

Return next_cursor: null on the final page rather than an empty array. Clients can then loop while (cursor) without a has_more flag that can disagree with the payload.

Idempotency Keys, Because Retries Are Inevitable

Every client will retry. Networks time out after the server has already committed, mobile apps get woken and re-send, load balancers occasionally duplicate a request. For POST /v1/orders a retry means two orders.

The fix is an Idempotency-Key header carrying a client-generated unique value, with the server storing the key, a hash of the request body, and the response it produced:

http
POST /v1/orders HTTP/1.1 Authorization: Bearer sk_live_... Content-Type: application/json Idempotency-Key: 7c1f2b9e-1d44-4b0a-9c33-2f6a51d0e8ab { "total_cents": 12900, "currency": "GBP", "items": [{ "sku": "TSHIRT-M", "quantity": 2 }] }
http
HTTP/1.1 201 Created Content-Type: application/json Idempotency-Key: 7c1f2b9e-1d44-4b0a-9c33-2f6a51d0e8ab { "data": { "id": "4521", "status": "pending", "total_cents": 12900 }, "meta": { "replayed": true } }
sql
create table idempotency_keys ( key text primary key, user_id uuid not null references auth.users (id) on delete cascade, request_hash bytea not null, response_status int, response_body jsonb, locked_until timestamptz not null default now(), created_at timestamptz not null default now() ); create index idempotency_keys_created_at_idx on idempotency_keys (created_at);

The rules that make this work are worth stating outright, and they are the same ones Stripe documents for their idempotency implementation:

  1. Scope the key to the client. A key stored globally lets one tenant collide with another and read someone else's response.
  2. Hash the request body. If the same key arrives with a different body, return 422. Silently replaying the old response for a different payload is worse than creating a duplicate.
  3. Keep keys for at least 24 hours. Client retry windows are longer than people assume; mobile clients in particular retry on the next app launch.
  4. Lock before doing the work. Insert the row first and let a unique violation return the stored response. Checking then inserting leaves a race wide enough for real traffic to walk through.

Expire rows with delete from idempotency_keys where created_at < now() - interval '2 days' in a scheduled job. Unbounded idempotency tables are a slow-motion outage.

Status Codes, Headers and Conditional Requests

Use codes consistently, because clients will branch on them. The set we use has not changed in years:

CodeUse it whenClient should
200GET, PUT, PATCH succeededRead the body
201Resource createdRead the body; honour Location
202Accepted for async processing, not donePoll the status resource
204DELETE succeeded, or PUT with no response neededExpect no body
400Body unparseableDo not retry unchanged
401Missing or invalid credentialsRefresh credentials once
403Authenticated but not permittedDo not retry; surface to user
404Resource does not exist, or you chose to hide that it doesDo not retry
409State conflict, e.g. duplicate keyRe-read state, then decide
422Parsed but failed validationFix the payload
429Rate limitedHonour Retry-After
500Unexpected failureRetry with backoff, at most a few times

Returning 404 rather than 403 for a resource the caller may not see is a deliberate choice, and it is the right one for tenant-scoped data — a 403 confirms the row exists.

Conditional requests cut bandwidth dramatically on endpoints with large, slowly-changing payloads. Return an ETag, and let the client send it back as If-None-Match:

http
HTTP/1.1 200 OK ETag: "orders-4521-v9" Cache-Control: private, max-age=0, must-revalidate { "data": { "id": "4521", "status": "shipped" } }

A matching If-None-Match gets 304 Not Modified and no body at all. Note Cache-Control: private — with a personalised payload, a shared cache leaking one customer's order into another's browser is a real and reportable class of bug. MDN's ETag reference covers the weak-validator syntax you need for generated responses.

Rate Limiting Without Surprises

Publish the limit, and publish how a client finds out it was hit. A 429 with a Retry-After header in seconds is the whole contract; the semantics are specified in RFC 6585.

http
HTTP/1.1 429 Too Many Requests Retry-After: 30 RateLimit-Limit: 1000 RateLimit-Remaining: 0 RateLimit-Reset: 30 { "error": { "code": "rate_limited", "message": "Limit of 1000 requests per minute exceeded." } }

Emit the RateLimit-* headers on 200 responses too. A client that can only discover the limit by being throttled will build a retry loop that keeps it throttled.

Documenting the Contract as an Executable Artifact

An OpenAPI document is not documentation you write; it is a description of the contract that can generate clients, drive tests and detect drift. The specification lives at spec.openapis.org, and the ecosystem is mature enough that a linter in CI is a one-line change:

yaml
openapi: 3.1.0 info: title: Example Orders API version: "1.4.0" paths: /v1/orders: get: operationId: listOrders parameters: - in: query name: limit schema: { type: integer, minimum: 1, maximum: 100, default: 25 } - in: query name: cursor schema: { type: string } responses: "200": description: A page of orders content: application/json: schema: $ref: "#/components/schemas/OrderPage" components: schemas: Order: type: object required: [id, status, total_cents, currency, created_at] properties: id: { type: string } status: { type: string, enum: [pending, paid, shipped, cancelled] } total_cents: { type: integer } currency: { type: string } created_at: { type: string, format: date-time } OrderPage: type: object required: [data, pagination] properties: data: type: array items: { $ref: "#/components/schemas/Order" }

Give every operation an operationId. It becomes the generated client method name, and listOrders is a far better story in an integration README than orders_list.

For third-party rate limiting strategies — token buckets, leaky buckets, and the failure modes when a limit is enforced in two places — read our post on API rate limiting. If you need this built as part of a product rather than a standalone service, our backend and API work sits inside web development, and SaaS development covers the billing and multi-tenant version of the same problems. If you would rather not spec it yourself, tell us what you are building.

How Ullass can help

This guide covers the theory. If you would rather have it implemented and operated for you, these are the services that cover it.

Related Articles

Ullass — Software Development Company

We build web apps, SaaS platforms, and digital products

Ullass designs, engineers, and scales software products for ambitious businesses. Also try our free online tools at tools.ullass.com. Questions? hello@ullass.com