REST API Fundamentals

Overview — what "REST" actually means in 2026

REST is not a library, not a protocol, not a framework. It's a set of architectural constraints Roy Fielding described in his 2000 dissertation — and most production "REST APIs" violate at least three of them. That's usually fine; what matters is understanding the constraints you're keeping and the ones you're breaking, so you can reason about caching, scaling, and security correctly.

We'll go through the handful of fundamentals every backend engineer and API pentester needs in their bones: HTTP verb semantics, idempotency, status codes, statelessness, content negotiation, caching and pagination. Each one has a visual so you can see the gap between an API that merely "feels RESTful" and one that actually behaves correctly under retries, scale and concurrent updates.

What this article is — and is NOT

HTTP verbs — semantics, safety, idempotency

Five core verbs cover ~99% of REST APIs. Each verb has a contract — what it does, whether it can be safely retried, whether it has side-effects. Picking the wrong verb usually doesn't cause functional bugs immediately, but it breaks caching, breaks retries, and signals to anyone reading your API that the underlying model is fuzzy.

The five verbs

Safety + idempotency cheat sheet

Verb Safe Idempotent Body request Body response Cacheable
─────────────────────────────────────────────────────────────────────────────
GET yes yes no yes yes
HEAD yes yes no no yes
OPTIONS yes yes no yes no
POST no no yes yes sometimes
PUT no yes yes optional no
PATCH no maybe yes optional no
DELETE no yes no optional no

"Safe" means the operation has no side effects — the server state after a GET is identical to the state before. "Idempotent" means N identical calls have the same effect as 1 call. GET is both. POST is neither. PUT/DELETE are idempotent but not safe (they DO change state, but the final state stabilises).

POST vs PUT — the most common confusion

Idempotency — surviving retries cleanly

Idempotency is the most under-appreciated REST property. The internet is not reliable — TCP timeouts, mobile hops, proxy hiccups, retry middleware, load-balancer failovers, browser refreshes. Any request can be retried by something somewhere in the chain. Idempotent operations survive retries cleanly; non-idempotent ones cause double-charges, duplicate orders, exploding queues.

Why this matters in production

Implementing idempotency for POST

The standard pattern (popularised by Stripe) is the Idempotency-Key header. Client generates a UUID per logical operation. Server stores key + result. On replay, server returns the stored result instead of executing the action again.

// client
const idempotencyKey = crypto.randomUUID();
fetch("/api/charges", {
 method: "POST",
 headers: {
 "Content-Type": "application/json",
 "Idempotency-Key": idempotencyKey
 },
 body: JSON.stringify({ amount: 1000, currency: "usd" })
});

// server (express + redis)
app.post("/api/charges", async (req, res) => {
 const key = req.header("Idempotency-Key");
 if (!key) return res.status(400).json({ error: "missing Idempotency-Key" });

 const existing = await redis.get(`idem:${key}`);
 if (existing) {
 // already processed — return stored response
 return res.status(200).json(JSON.parse(existing));
 }

 const result = await chargeCustomer(req.body);
 // store for 24h — long enough to cover any reasonable retry window
 await redis.set(`idem:${key}`, JSON.stringify(result), "EX", 86400);
 res.json(result);
});

Idempotency-Key for non-POST verbs

PUT, DELETE, GET are already idempotent by spec — you don't normally need a key. But for distributed write-ahead patterns (multi-region writes, eventual-consistency stores), even PUTs can benefit from an explicit key so you can reason about which write "wins". Most APIs only use the key on POST.

Status codes — the response contract

A 200 carrying {"error": "not found"} is the most common API design mistake on the internet. The status code is part of your response contract — proxies cache on it, monitoring alerts on it, retry libraries make decisions on it. Return 200 for an error and you've quietly broken every layer of the stack that was supposed to react to the failure.

The five families

The "which 4xx do I pick" question

5xx — never leak internals

// BAD — leaks stack trace, framework, version, library names
HTTP/1.1 500 Internal Server Error
{
 "error": "TypeError: Cannot read property 'name' of undefined",
 "stack": "at /app/src/users.ts:42:18\n at /app/node_modules/express/...",
 "node_version": "20.10.0"
}

// GOOD — generic message + correlation ID to find it in logs
HTTP/1.1 500 Internal Server Error
{
 "error": "Internal server error",
 "correlationId": "8f3a2b1c-…"
}

// the actual error + stack trace goes to your server logs, indexed by correlationId

Statelessness — why each request stands alone

Of Fielding's six REST constraints, statelessness is the one most directly tied to scaling. Every request must carry everything the server needs to understand it — no "remember that I was on step 3 of the wizard" sitting in one server's memory. The payoff is that any server in your fleet can handle any request. The cost is that every request is a little bigger, revocation gets harder, and the client carries more of the weight.

Stateless vs server-side session

Common statelessness violations

Stateless does NOT mean "no state anywhere"

Servers obviously have state — the database, the cache, the queue. Statelessness in REST is specifically about not stashing per-conversation state in a single server's memory. Database state is fine. A user session in Redis is fine too — technically stateful, but it's a centralised cache any server can read. What isn't fine is "server A remembers something about this client that server B doesn't."

Content negotiation — one resource, many representations

Same resource, multiple representations. The Accept header lets a client say "I want this as JSON" while a legacy integration says "give me XML" and a spreadsheet export says "give me CSV". The server picks the best match it can produce. Powerful, often under-used in modern APIs.

The negotiation headers

q-values — the quality / preference scale

Accept: application/json;q=1, application/xml;q=0.7, text/csv;q=0.3, */*;q=0.1
// ^^^^^^^^^^^^^^^^^^ prefer JSON (default q=1)
// ^^^^^^^^^^^^^^^^^^ XML OK, 0.7 preference
// ^^^^^^^^^ CSV grudgingly accepted
// ^^^^^^^^^ anything is better than nothing

// server returns the highest-q match it can produce
// if it can do JSON: JSON. if not JSON but yes XML: XML. and so on.

Versioning via content negotiation

A popular pattern is to version your API by mime-type rather than by URL. Accept: application/vnd.example.user+json; version=2. The URL stays the same; the response format reflects the requested version. Avoids the /v1/, /v2/ URL proliferation. GitHub's API used this for years.

// versioning by content negotiation
GET /users/42
Accept: application/vnd.example.user+json; version=2

// vs URL-based versioning
GET /v2/users/42
Accept: application/json

Caching — ETag, Cache-Control, and the 304 win

REST over HTTP hands you a powerful caching layer for free — if you actually use it. Most APIs ignore Cache-Control and ETag completely and leave 90%+ of their bandwidth on the table. A properly cached API is faster, cheaper and more scalable than any in-process LRU you could hand-roll.

The caching headers

ETag flow — the 304 win

// 1) first request, no cache
GET /products HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json
ETag: "v1-abc123"
Cache-Control: no-cache
Vary: Accept

[... 50 KB body ...]

// client stores: body + ETag

// 2) later, client wants the same resource
GET /products HTTP/1.1
Accept: application/json
If-None-Match: "v1-abc123"

HTTP/1.1 304 Not Modified
ETag: "v1-abc123"
Cache-Control: no-cache

// empty body. client uses its cached copy. ~200 bytes vs 50 KB.

// 3) data changes server-side, ETag becomes "v2-def456"
GET /products HTTP/1.1
If-None-Match: "v1-abc123"

HTTP/1.1 200 OK
ETag: "v2-def456"
[... 52 KB new body ...]
// client refreshes its cache.

Strong vs weak ETags

ETag: "abc123" # strong — bytes must be identical
ETag: W/"abc123" # weak — semantically equivalent OK

Strong ETags require byte-for-byte match — used when range requests / byte caching matter. Weak ETags allow representations that are semantically equivalent (e.g., same JSON with different key order). For most REST APIs, weak is fine.

Cache poisoning — the security angle

Pagination — offset vs cursor

Returning unbounded collections is a denial-of-service speedrun. Every list endpoint needs pagination. The choice between OFFSET and CURSOR pagination determines whether your API stays correct as the underlying data changes mid-fetch — which it always does in real systems.

Offset vs cursor — the comparison

Why offset gets slow at scale

-- SELECT * FROM items LIMIT 10 OFFSET 100000
-- DB must read AND DISCARD 100,000 rows before returning the 10 you want
-- O(N) per page, terrible for deep pagination

-- vs cursor (using indexed id):
-- SELECT * FROM items WHERE id > 99999 LIMIT 10
-- DB does an index seek to id=99999 then reads 10 rows. O(log N) regardless of depth.

The Link header — RFC 5988

// the standard way for a paginated response to point to next/prev pages
HTTP/1.1 200 OK
Link: <https://api.example.com/items?after=item_30&limit=10>; rel="next",
 <https://api.example.com/items?before=item_21&limit=10>; rel="prev",
 <https://api.example.com/items?limit=10>; rel="first"
X-Total-Count: 1543

[items 21..30 here]

// client follows Link rel="next" without having to construct the URL itself
// (this is the closest most APIs come to HATEOAS — see s9)

Pagination + filtering + sorting

GET /items?
 filter[status]=active&
 sort=-created_at& # leading "-" = descending
 fields=id,name,price& # sparse fieldset
 after=item_30&
 limit=20

// the JSON:API spec standardises this shape. follow it if you don't have a strong reason otherwise.

URL design + a brief word on HATEOAS

URL design isn't about following a manifesto — it's about being predictable. Conventions reduce cognitive load for every developer who reads your API.

URL design conventions

HATEOAS — the constraint nobody actually follows

Hypermedia As The Engine Of Application State — Fielding's strictest REST constraint. Responses should include links to related resources, so clients can navigate the API without hard-coding URLs.

// strict HATEOAS response
{
 "id": 42,
 "name": "alice",
 "email": "[email protected]",
 "_links": {
 "self": { "href": "/users/42" },
 "orders": { "href": "/users/42/orders" },
 "manager": { "href": "/users/13" },
 "deactivate": { "href": "/users/42", "method": "DELETE" }
 }
}

// client follows _links rather than computing URLs from a template.
// the server can change URLs without breaking clients.

In practice, almost no production API follows HATEOAS strictly because clients usually have hard-coded URL templates anyway, and the verbosity isn't worth it. The lightest version — including self link and next/prev for paginated responses (cf. §8) — captures most of the benefit.

Errors — Problem+JSON, validation, enumeration leaks

Status codes communicate the high-level outcome. The response body should communicate the detail. Inconsistent error shapes are the single biggest cause of "I can't figure out what your API is telling me" in client integrations.

RFC 7807 — Problem Details for HTTP APIs

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
 "type": "https://example.com/probs/validation",
 "title": "Validation failed",
 "status": 422,
 "detail": "The submitted form has 2 errors.",
 "instance": "/orders/draft/abc123",
 "errors": [
 { "field": "items[0].quantity", "message": "must be positive" },
 { "field": "shipping.postalCode", "message": "invalid format" }
 ]
}

RFC 7807 (problem+json) is the closest thing to an industry standard for API error responses. It gives clients a stable shape — type, title, status, detail, instance, plus your own fields. Even if you don't adopt it formally, copy the shape.

Validation patterns

Don't over-leak in 4xx either

Security fundamentals — the baseline checklist

REST API security is a deep topic in its own right — the API Top 10 articles cover it properly. The fundamentals below are just the floor:

Foundational security checklist

Pentester quick-look

# 1. enumerate endpoints
gobuster dir -u https://api.example.com -w api-wordlist.txt
ffuf -u https://api.example.com/FUZZ -w api-wordlist.txt

# 2. fetch OpenAPI / swagger
curl https://api.example.com/openapi.json
curl https://api.example.com/swagger.json
curl https://api.example.com/v2/api-docs

# 3. check verb support per endpoint
for v in GET POST PUT PATCH DELETE OPTIONS; do
 echo -n "$v "; curl -s -o /dev/null -w "%{http_code}\n" -X $v https://api.example.com/users/42
done

# 4. flip every id (BOLA) — see "BOLA / IDOR" article
curl https://api.example.com/users/1 -H "Authorization: Bearer $T_USER1"
curl https://api.example.com/users/2 -H "Authorization: Bearer $T_USER1" # should 403 or 404

# 5. abuse pagination
curl "https://api.example.com/items?limit=999999" # capped?
curl "https://api.example.com/items?offset=-1" # validated?
curl "https://api.example.com/items?sort=password" # sortable on private field?

# 6. test idempotency
for i in 1 2 3; do
 curl -X POST https://api.example.com/orders -d '{"item":"x"}' -H "Idempotency-Key: same-key-here"
done

# 7. test rate limiting
seq 1 1000 | xargs -P 50 -I _ curl -s https://api.example.com/endpoint -o /dev/null -w "%{http_code}\n" | sort | uniq -c

Cheat sheet — verbs, codes, headers, tools

A quick reference for the people designing and reviewing these APIs:

REST cheat sheet

Status code cheat sheet

Headers worth knowing

Tools

Closing thoughts

Three things to take away:

HTTP isn't just the transport — it's the contract. Verbs, status codes, headers, ETags all carry real meaning that proxies, caches, monitoring and clients depend on. Returning 200 { error } isn't creative design, it's breaking the contract every layer of your stack assumes. Lean into HTTP semantics and you get caching, retries, observability and easy integrations for free.

Idempotency isn't optional for write APIs. The network will fail and clients will retry — both are certainties. Every POST without an Idempotency-Key is a duplicate charge waiting to page someone at 3am. The implementation is about twenty lines of Redis-backed middleware; skipping it gets paid for in support tickets and refunds instead.

Most "REST" APIs aren't really REST, and that's fine. Pure HATEOAS, strict resource modelling, hypermedia state machines — interesting ideas that mostly don't survive contact with production. What does survive is predictable URLs, correct verbs, honest status codes, idempotent writes, stable pagination and sensible caching. Get those right and your API is a pleasure to integrate with, REST orthodoxy or not.

Next on the API Security track: API Authentication — Bearer tokens, mTLS, HMAC signing — then Postman/Insomnia for pentesting, then the API Top 10. Everything there builds on the fundamentals here.