Complete REST
API Design

In 1990 Tim Berners-Lee started a project to share knowledge across the world — the World Wide Web. Within about a year he invented essentially everything we still use: the URI (uniform resource identifier), the HTTP protocol, HTML, the first web server, the first browser, and the first WYSIWYG HTML editor built into that browser. Remarkable for one person in twelve months.

Then the problem arrived: scale. The web grew exponentially, far past anything Berners-Lee had planned for. The original design simply could not absorb the user base it was acquiring every day. Around 1993, Roy Fielding — co-founder of the Apache HTTP server project — got concerned about exactly this. To make the web scalable he proposed a set of architectural constraints. He and Berners-Lee then co-wrote the specification for HTTP/1.1, the first standardized version of the protocol. Finally, in 2000, Fielding named and described the whole architectural style in his PhD dissertation: REST — REpresentational State Transfer.

The name decomposes into three ideas, and each one is a real concept you use every day:

Representational

A resource (a piece of data — a user, a book, a cart) can be represented in different formats depending on who's asking. The same user record might be sent as JSON to an API client (server-to-server), or as HTML to a browser, or as XML to some legacy consumer. The underlying resource is one thing; its representations are many.

State

State is the current condition of a resource — its present attributes. Think of an Amazon shopping cart: its state is the set of items in it, their quantities, and the total price right now. That state lives on the server and is what gets moved around.

Transfer

Because we have a client and a server, the whole point is moving these representations between them. The transfer happens over the common standard — HTTP — using its methods (GET, POST, PUT, PATCH, DELETE, …). When your browser asks for a page with GET, it's transferring a representation from server to client.

To be truly "RESTful" — and to get the scalability Fielding was after — a system follows six constraints. Five are required; the sixth is optional. These aren't bureaucracy; each one buys a concrete scaling property.

The two that matter most in practice

Stateless is the heavy hitter. The server does not remember your previous request — every request must contain all the information needed to understand and process it. This is what makes scaling possible: put a load balancer in front of three identical servers, and because no server holds your session in memory, any of them can handle any request via round-robin. Statelessness is the reason you can add servers and they "just work."

Layered System is what statelessness enables. Because the client only ever talks to the layer immediately in front of it, you can slip in CDNs, reverse proxies, load balancers, and API gateways between client and origin — and the client never knows or cares. This is the entire foundation of how a small app grows into one serving millions.

The four sub-constraints of Uniform Interface

• Resource identification — every resource is addressable by a URI.
• Manipulation through representations — you act on a resource by sending/receiving its representation (the JSON you PUT is how you change it).
• Self-descriptive messages — each message carries enough metadata (headers, content-type, method) to be understood on its own.
• HATEOAS — Hypermedia As The Engine of Application State: responses can include links telling the client what it can do next. (The most aspirational sub-constraint; few APIs implement it fully.)

Here's the honest backstory the transcript leans on: people still get tripped up by REST — plural or singular path? PUT or PATCH? which status code for a custom action? — and the reason is historical. When these standards were forming, the web ran on MPAs (multi-page applications): every interaction was a full-page request to the server, which rendered HTML and sent it back.

Today we mostly build SPAs (single-page applications): the first request downloads a big bundle of JavaScript, and from then on the browser does its own routing on the client side, fetching data (JSON) from APIs rather than whole pages. The client got heavy; the server became a pure data API. The old standards never anticipated this shift, which is why some of their rules feel ambiguous against modern usage.

Start with a normal website URL and its parts:

The industry-standard shape of an API route (a convention, not a hard rule) layers these together: https:// + an api. subdomain + a version like /v1 + the resource path.

Rule 1 — always plural nouns

The resource in the path is always plural, even when fetching a single item. List all books → /books. Fetch one book → /books/123, not /book/123. The resource type ("books") is a collection; the ID just narrows into it. This is the single most common beginner mistake.

Rule 2 — no spaces or underscores; use slugs

URLs travel across many server/client/OS environments, so keep them clean. Never put spaces or underscores in a path. To put a human-readable name in a URL, build a slug:

Rule 3 — the slash means hierarchy

A forward slash expresses a hierarchical relationship between resources. /organizations/123/projects reads as "the projects that belong specifically to organization 123." First level: the collection. Next level: a specific member. Next: that member's sub-collection. Design your paths so the nesting tells the story.

Idempotency is the concept that unlocks "which method should I use?" An operation is idempotent if performing it many times has the same effect on the server as performing it once. The key subtlety: idempotency is about the side effect you cause on the server, not about whether the response bytes are identical.

GET — idempotent & safe

Fetches data; changes nothing on the server. Call it once or a thousand times — the server state is identical. "But what if someone else creates a book between my calls and the response changes?" That doesn't break idempotency: idempotency asks what side effect your call causes, and a GET causes none. Because it's safe, it's freely retryable and cacheable.

On the wire, a GET is just a request line, headers, and a blank line — no body. All input rides in the URL (path + query string), which is why you never put secrets in a GET: the whole URL lands in browser history, server logs, and CDN logs.

PUT & PATCH — idempotent updates

Both update. The difference is scope:

• PATCH — partial update. Send only the fields you want to change (e.g. just status). Best fit for SPA-era JSON apps, where you almost always update a few fields, not the whole record.
• PUT — full replacement. You must send the entire representation; the server replaces what it has with your payload. Omit a field and you've wiped it.

Why idempotent? Say a user's name is A and you PATCH it to B. First call: A → B. Second identical call: B → B. Thousandth call: still B. The end state never changes after the first call, so repeating the same update payload is idempotent.

On the wire — the body is the whole difference

Concurrent edits — the lost-update problem

Two clients GET the same record. A changes the email and saves. B (who never saw A's change) saves the city using B's stale copy — and B's write silently overwrites A's email. The fix is optimistic concurrency with ETag + If-Match: the server hands out a version fingerprint, and only applies your write if that version is still current.

func UpdateOrganization(w http.ResponseWriter, r *http.Request) {
	id := r.PathValue("id")
	org := store.Get(id)
	if org == nil {
		writeJSON(w, 404, errBody("organization not found"))
		return
	}
	// optimistic concurrency: reject stale writes
	if m := r.Header.Get("If-Match"); m != "" && m != org.ETag {
		writeJSON(w, 412, errBody("resource changed; re-fetch and retry"))
		return
	}
	var patch map[string]any
	json.NewDecoder(r.Body).Decode(&patch) // only the fields to change
	updated := store.Patch(id, patch)        // merge, don't replace
	w.Header().Set("ETag", updated.ETag)
	writeJSON(w, 200, updated)               // 200 + updated entity
}

@app.patch("/v1/organizations/{id}")
def update_organization(id: str, body: dict, if_match: str | None = Header(None)):
    org = store.get(id)
    if org is None:
        raise HTTPException(404, "organization not found")
    # optimistic concurrency: reject stale writes
    if if_match is not None and if_match != org.etag:
        raise HTTPException(412, "resource changed; re-fetch and retry")
    updated = store.patch(id, body)   # merge only the given fields, don't replace
    return Response(
        content=json.dumps(updated),
        media_type="application/json",
        headers={"ETag": updated["etag"]},
    )                                  # 200 + updated entity

DELETE — idempotent

Delete user 1. First call: the user is removed (a real side effect). Second call: the server checks, finds no such user, and returns 404 — but nothing changed on the server. No new side effect occurred. You only changed state on the first call; every call after that is a no-op that simply reports "not found." Hence DELETE is idempotent.

POST — the only non-idempotent one

POST creates. Send a "create book" payload once → one book with ID 1. Send the exact same payload again → a second book with ID 2 (IDs are generated server/DB-side, and names usually needn't be unique). Ten identical POSTs → ten distinct books. The side effect changes every time, so POST is non-idempotent.

On the wire, POST carries a body (declared by Content-Type), and a successful create returns 201 with a Location header pointing at the new resource:

func CreatePayment(w http.ResponseWriter, r *http.Request) {
	key := r.Header.Get("Idempotency-Key") // client-generated UUID

	// already processed this exact request? return the SAME result, don't re-charge
	if prior, ok := idemStore.Get(key); ok {
		writeJSON(w, prior.Status, prior.Body)
		return
	}

	var in struct{ Amount int `json:"amount"` }
	json.NewDecoder(r.Body).Decode(&in)

	payment := charge(in.Amount)          // the real, non-idempotent side effect
	idemStore.Save(key, 201, payment)     // remember it, keyed by the idempotency key
	writeJSON(w, 201, payment)
}

@app.post("/v1/payments", status_code=201)
def create_payment(body: dict, idempotency_key: str = Header(...)):
    # already processed this exact request? return the SAME result, don't re-charge
    prior = idem_store.get(idempotency_key)
    if prior is not None:
        return JSONResponse(status_code=prior["status"], content=prior["body"])

    payment = charge(body["amount"])               # the real, non-idempotent side effect
    idem_store.save(idempotency_key, 201, payment) # remember it, keyed by the idempotency key
    return payment

Sometimes an action doesn't fit Create/Read/Update/Delete. "Clone a project," "archive an organization," "send an email" — these trigger a web of background work beyond a simple database write. The REST spec makes POST the open-ended method for exactly these cases.

The rule & the route shape

When an action doesn't map to a standard method, make it a POST and append the action as a verb at the end of a specific resource path:

This keeps the hierarchy honest: all organizations → one specific organization → the action to run on it.

The "send email" example

Consider POST /emails with body {"target": "someone@example.com"}. Is sending an email a fetch? No. A create? Not really. An update or delete? No. It's a custom action — so it lives under POST. And note: a custom action POST often returns 200 OK (the action ran), not 201 Created, because nothing new was necessarily created. Never assume "POST ⇒ 201."

A list endpoint can't just dump every row. Three features make it robust, and all three ride on query parameters.

Pagination — why & how

Returning a thousand records at once is expensive on both ends: JSON serialization/deserialization is heavy work, the network bottlenecks, and the user perceives a multi-second delay — even though on screen they only see the first 10–20 items before scrolling. So the server returns the data in chunks (pages).

A paginated response includes four fields:

• data — the array of items for this page.
• total — the absolute count of items in the DB (so the UI can say "showing 10 of 50").
• page — which page this response represents.
• totalPages — the maximum number of pages (the frontend uses this to know when to stop fetching on infinite scroll: when page === totalPages, stop).

The client controls it with two params: limit (how many per page) and page (which chunk). And — a sane-defaults moment — if the client sends neither, the server should default page to 1 and limit to something like 10 or 20, never crash.

Sorting

Two params: sortBy (which field) and sortOrder (ascending / descending). Crucial default: even with no sort params, the server must sort by something — otherwise the DB returns rows in arbitrary order and the same call yields different orderings each time. The natural default is sortBy=createdAt, sortOrder=descending (newest first).

Filtering

Pass resource fields as query params to narrow the list: ?status=active, or combine them: ?status=archived&name=org. The server applies each as a filter on the result set.

// GET /v1/organizations?status=active&sortBy=name&sortOrder=ascending&page=1&limit=10
func ListOrganizations(w http.ResponseWriter, r *http.Request) {
	q := r.URL.Query()

	// --- sane defaults: never crash if the client omits params ---
	page := atoiDefault(q.Get("page"), 1)
	limit := atoiDefault(q.Get("limit"), 10)
	sortBy := defaultStr(q.Get("sortBy"), "createdAt")
	sortOrder := defaultStr(q.Get("sortOrder"), "descending")

	filters := map[string]string{}
	if s := q.Get("status"); s != "" {
		filters["status"] = s // ?status=active
	}

	rows, total := store.Query(filters, sortBy, sortOrder, page, limit)
	totalPages := (total + limit - 1) / limit // ceil division

	writeJSON(w, 200, map[string]any{
		"data":       rows,
		"total":      total,
		"page":       page,
		"totalPages": totalPages,
	})
}

# GET /v1/organizations?status=active&sortBy=name&sortOrder=ascending&page=1&limit=10
@app.get("/v1/organizations")
def list_organizations(
    status: str | None = None,
    sortBy: str = "createdAt",        # sane default
    sortOrder: str = "descending",    # sane default
    page: int = 1,                    # sane default
    limit: int = 10,                  # sane default
):
    filters = {}
    if status:
        filters["status"] = status    # ?status=active

    rows, total = store.query(filters, sortBy, sortOrder, page, limit)
    total_pages = (total + limit - 1) // limit   # ceil division

    return {
        "data": rows,
        "total": total,
        "page": page,
        "totalPages": total_pages,
    }

The 404 rule — the one people get wrong

Return 404 only when a client requests a specific single resource that doesn't exist (e.g. GET /users/999). If a client hits a list API and nothing matches (e.g. "all users named Zack," or a filter that matches nothing), do not return 404. Return 200 OK with an empty array []. A list that found nothing still succeeded — it just found nothing.

The five families — read the first digit

Every status code's first digit tells you almost everything. This is the fastest debugging instinct you can build.

The 4xx codes people confuse

401 vs 403

401 Unauthorized means "I don't know who you are" — no credentials, or they're invalid/expired. The fix is to log in or refresh the token. 403 Forbidden means "I know exactly who you are, and you're not allowed" — valid credentials, insufficient permission. Logging in again won't help. (The names are historically swapped — 401 is really about authentication, 403 about authorization.)

409 Conflict

The request collides with the current state of the resource: creating something that already exists, a unique-field clash, or deleting something other records still depend on ("can't delete a user with active orders").

422 vs 400

400 Bad Request = the request is malformed at the syntax level (broken JSON, a string where a number was required). 422 Unprocessable Entity = the syntax is perfect, but it fails a semantic/business rule (a negative age, an email that isn't an email, an end-date before the start-date). Use 422 when you parsed the body fine but the values don't make sense.

429 Too Many Requests

Rate-limited. Respect the Retry-After header (seconds to wait) instead of hammering, or you'll just stay throttled.

The codes you'll meet 90% of the time

Following the transcript's build: a project-management product (think Jira / Linear). From the wireframes we extract the nouns → resources: organizations, projects, tasks (also users, tags). Those become tables, then endpoints. Here's the full endpoint set for one resource — the same pattern repeats for every other resource.

Notice the symmetry: list and create share the collection URL (/organizations) and differ only by method — the server routes GET to the list handler and POST to the create handler. Likewise get-one / update / delete share /organizations/:id and differ only by method. The custom action appends a verb. projects would mirror this exactly, with clone as its custom action.

func RegisterOrgRoutes(mux *http.ServeMux) {
	// list + create share the collection URL, split by method
	mux.HandleFunc("GET /v1/organizations", ListOrganizations)
	mux.HandleFunc("POST /v1/organizations", CreateOrganization)

	// get-one / update / delete share /:id, split by method
	mux.HandleFunc("GET /v1/organizations/{id}", GetOrganization)
	mux.HandleFunc("PATCH /v1/organizations/{id}", UpdateOrganization)
	mux.HandleFunc("DELETE /v1/organizations/{id}", DeleteOrganization)

	// custom action: verb at the end of a specific resource
	mux.HandleFunc("POST /v1/organizations/{id}/archive", ArchiveOrganization)
}

func CreateOrganization(w http.ResponseWriter, r *http.Request) {
	var in struct {
		Name        string `json:"name"`
		Status      string `json:"status"`
		Description string `json:"description"`
	}
	json.NewDecoder(r.Body).Decode(&in)

	if in.Status == "" {
		in.Status = "active" // sane default — don't force the client to send the obvious
	}
	org := store.Insert(in.Name, in.Status, in.Description) // id, createdAt set server-side
	writeJSON(w, 201, org) // 201 Created + the new entity
}

func DeleteOrganization(w http.ResponseWriter, r *http.Request) {
	store.Delete(r.PathValue("id"))
	w.WriteHeader(204) // No Content
}

func ArchiveOrganization(w http.ResponseWriter, r *http.Request) {
	org := store.Archive(r.PathValue("id")) // flips status + cascades: projects, tasks, emails...
	writeJSON(w, 200, org) // custom action → 200, NOT 201
}

from fastapi import FastAPI, Response
app = FastAPI()

# list + create share the collection URL, split by method
@app.get("/v1/organizations")
def list_organizations(): ...      # (see section 07)

@app.post("/v1/organizations", status_code=201)   # 201 Created
def create_organization(body: dict):
    status = body.get("status") or "active"        # sane default
    return store.insert(                            # id, createdAt set server-side
        name=body["name"], status=status, description=body.get("description"),
    )

# get-one / update / delete share /{id}, split by method
@app.get("/v1/organizations/{id}")
def get_organization(id: str):
    org = store.get(id)
    if org is None:
        raise HTTPException(404, "organization not found")  # single id → 404
    return org

@app.patch("/v1/organizations/{id}")                # partial update → 200
def update_organization(id: str, body: dict):
    return store.update(id, body)

@app.delete("/v1/organizations/{id}", status_code=204)  # No Content
def delete_organization(id: str):
    store.delete(id)
    return Response(status_code=204)

# custom action: verb at the end → POST, returns 200 (created nothing)
@app.post("/v1/organizations/{id}/archive")
def archive_organization(id: str):
    return store.archive(id)   # flips status + cascades: projects, tasks, emails...

Extract nouns from the UI first

Before writing a line of business logic, look at the wireframes (Figma) or talk to the product people. The nouns users interact with — projects, users, tasks, tags — are your resources. Looking at how the end-user touches data tells you how the lowest layer (the DB) relates to the top layer (the screen), and that's the right place to start designing the interface.

Design the interface before coding

A REST API is designed, not programmed-first. Lay out routes, payloads, and responses in a tool like Insomnia or Postman before touching Go, Python, or any framework. The whole point is a delightful, intuitive, unambiguous interface — so the consumer never has to read your source code or guess your behavior by trial and error.

Provide sane defaults

Never crash because the client omitted something obvious. No page → default 1. No limit → default 10. No sortBy → createdAt descending. No status on create → active. Require only the information you genuinely cannot infer.

Be ruthlessly consistent

• JSON in camelCase, always — both payloads and responses.
• No abbreviations — if a field is description, never call it desc in another endpoint. You have context the consumer doesn't; an abbreviation they can't decode costs them a failed call and a docs hunt.
• Same shapes across resources — if organizations are plural and paginated with {data,total,page,totalPages}, then projects and tasks are too. Consumers integrate one endpoint, then assume the rest follow the same style. Reward that assumption.

Ship interactive docs

Generate an interactive playground with Swagger / OpenAPI from the start. It doubles as documentation for frontend engineers integrating you, and as a testing ground for you. How consistently you maintain your OpenAPI spec genuinely sets you apart.

The moment another team or another company integrates your API, you can no longer change it freely — a field you rename or a response you reshape breaks their code in production. Versioning is how you evolve without breaking what's already deployed. Three common strategies:

When to bump the version

Only on a breaking change — something that would break an existing consumer:

• Removing or renaming a field; changing its type or meaning.
• Removing an endpoint, or changing its method/route.
• Making a previously-optional field required, or changing default behavior.

Additive changes are NOT breaking — and don't need a new version. Adding a new optional field, a new endpoint, or a new optional query param leaves old clients working untouched (they just ignore what they don't know about). Bumping the version for additive changes is needless churn.

People design the happy path carefully and then return raw stack traces or bare strings on failure. But the error shape is part of your API contract too — the consumer's error-handling code depends on it being consistent and machine-readable. A status code alone isn't enough; the body should explain what went wrong in a predictable structure.

A consistent error envelope

Pick one error shape and use it on every error, across every endpoint. A solid, minimal envelope:

Why each piece earns its place:

• code — a stable string the client can switch on. Never make them parse the human message; messages get reworded, codes don't.
• message — for humans/logs. Safe to show or surface.
• details — per-field errors so a form can highlight exactly which inputs failed (pairs naturally with 422).
• requestId — the single most useful field in production: the consumer quotes it in a bug report and you find the exact request in your logs in seconds.

type FieldError struct {
	Field string `json:"field"`
	Issue string `json:"issue"`
}

func writeError(w http.ResponseWriter, status int, code, msg string, details ...FieldError) {
	body := map[string]any{"error": map[string]any{
		"code":      code,
		"message":   msg,
		"details":   details,
		"requestId": requestIDFromCtx(),
	}}
	writeJSON(w, status, body) // SAME shape for every error in the whole API
}

// usage
writeError(w, 422, "validation_failed", "Some fields are invalid.",
	FieldError{"email", "must be a valid email"},
	FieldError{"age", "must be >= 0"},
)

from fastapi import Request
from fastapi.responses import JSONResponse

def error_response(status, code, message, details=None, request_id=""):
    return JSONResponse(status_code=status, content={"error": {
        "code": code,
        "message": message,
        "details": details or [],
        "requestId": request_id,
    }})  # SAME shape for every error in the whole API

# usage
error_response(
    422, "validation_failed", "Some fields are invalid.",
    details=[
        {"field": "email", "issue": "must be a valid email"},
        {"field": "age",   "issue": "must be >= 0"},
    ],
)