REST API Design

Here's REST in plain English. You're building an APIApplication Programming Interface — a way for programs to talk to each other. When a mobile app fetches your profile from Instagram, it's calling Instagram's API. Think of it as a waiter taking your order to the kitchen and bringing back food. — a way for other programs to talk to your system. Instead of inventing a brand-new command for every action (getUser, fetchAllOrders, createNewProduct, removeItemFromCart), you organize everything around resources — the "things" in your system. Users, orders, products, carts. Each thing gets a URL. And the action you want to take? That's just the HTTP methodThe verb in an HTTP request — GET (read), POST (create), PUT (replace), PATCH (update partially), DELETE (remove). Think of them as the 5 things you can do to any resource. — GET to read, POST to create, PUT to replace, PATCH to tweak, DELETE to remove.

Don't take our word for it. Open a terminal right now and try this:

# This is a REAL API call to GitHub. Try it.
curl https://api.github.com/users/torvalds

# What you get back:
# {
#   "login": "torvalds",
#   "id": 1024025,
#   "name": "Linus Torvalds",
#   "company": "Linux Foundation",
#   "public_repos": 7,
#   "followers": 221000,
#   ...
# }

# That's REST. The URL (/users/torvalds) is the NOUN.
# The HTTP method (GET) is the VERB.
# The response is JSON — structured data.

That's a real REST API running in production right now. GitHub serves billions of these requests every day. The URL /users/torvalds is the resource (the noun — "Linus Torvalds's profile"). The HTTP method GET is the action (the verb — "read it"). The response is JSONJavaScript Object Notation — a lightweight format for sending data between systems. It looks like: {"name": "Linus", "repos": 7}. Nearly every REST API uses JSON because it's human-readable and easy for code to parse. — structured data your code can parse.

Once you learn this pattern, you can use any REST API — Stripe, GitHub, Twilio, Twitter — without reading much documentation, because they all speak the same language. The URLUniform Resource Locator — the address of a resource on the internet. In REST, the URL tells you WHAT thing you're working with (/users/42 = user #42). The HTTP method tells you WHAT you're doing to it (GET = read it, DELETE = remove it). tells you what you're talking about, and the method tells you what you want to do.

You join a startup. The product is growing fast. There's a backend with 47 API endpoints. Your first task: build a new feature in the mobile app that shows order history. You ask the backend team, "What's the endpoint for getting a user's orders?"

Silence. Then: "Check Slack, someone posted it once." You dig through Slack messages and piece together a few endpoints. They look like this:

# User endpoints — different naming styles
POST /getUserProfile           ← RPC-style, verb in URL
GET  /api/v2/fetch-orders?userId=5&sortBy=date  ← mixed conventions
POST /deleteAccount            ← POST for deletion??
GET  /api/getProductsByCategory?cat=electronics&page=2&limit=50

# Cart endpoints — even the team doesn't agree
POST /addToCart                 ← no resource noun
POST /cart/remove-item          ← kebab-case here
GET  /getCartItems?userId=7    ← camelCase there

# Order endpoints — chaos
POST /submitOrder
GET  /getOrderStatus?orderId=99
POST /order/cancel              ← completely different structure

A new developer joins and asks: "Where's the documentation?" There is none. "OK, how do I update a user?" Nobody knows if it's PUT or POST or PATCH. Three different people wrote these endpoints over 18 months, and each one followed their own convention. The API isn't wrong — it works. But nobody can use it without asking someone.

The messy API in Section 2 isn't random chaos. It's actually following a very common approach called RPC-styleRemote Procedure Call — an API style where each endpoint is a function name (verb + noun), like calling a method on a remote server. Examples: /getUser, /createOrder, /deleteItem. The URL IS the function name.. The idea is dead simple: every endpoint is a function call. You name the URL after what it does, exactly like you'd name a function in your code.

This isn't some outdated idea that nobody uses. Slack's entire API works this way right now. Open their API docs and you'll see real endpoints like these:

# Slack's actual API endpoints (still in use today)
POST https://slack.com/api/chat.postMessage
POST https://slack.com/api/channels.list
POST https://slack.com/api/users.info
POST https://slack.com/api/files.upload
POST https://slack.com/api/reactions.add
POST https://slack.com/api/conversations.history

# Notice: EVERYTHING is POST.
# The URL IS the function name.
# The action is baked into the URL path.

And honestly? For small projects, this works fine. If you have 5 endpoints, naming them /getUser, /createUser, /deleteUser, /getOrders, /createOrder is easy enough. Everyone on the team knows what each one does. Slack has hundreds of millions of users and their RPC-style API handles it just fine.

The problem isn't that RPC is "wrong." Slack proves it works at massive scale. The problem is it doesn't scale as a convention. With 5 endpoints, you can memorize them. With 50, you need documentation for every single one. With 200, even the people who built the API can't remember all the names. There's no pattern to learn — every endpoint is a snowflake.

Here's the real kicker: can you guess what Slack's endpoint for editing a message is? Is it chat.editMessage? Or chat.update? Or messages.edit? (It's actually chat.update — you'd never guess that without reading the docs.) Now compare that to GitHub's REST API: if you know GET /repos/{owner}/{repo} fetches a repo, can you guess how to get its pull requests? GET /repos/{owner}/{repo}/pulls. And you'd be right. That's the difference between a convention you have to memorize vs. a convention you can predict.

RPC-style APIs don't fail in theory. They fail in practice, at scale, with real money on the line. Here are three specific problems — each one illustrated with a real company that hit it.

# HEAD request — just the headers, no body
curl -I https://api.github.com/users/torvalds

# Response headers (the ones that matter):
# HTTP/2 200
# cache-control: public, max-age=60, s-maxage=60
# etag: "abc123..."
# last-modified: Mon, 15 Jan 2024 10:30:00 GMT
# x-ratelimit-limit: 60
# x-ratelimit-remaining: 57

# See those? cache-control, etag, last-modified.
# These tell CDNs and browsers: "Cache this for 60 seconds.
# After that, check if it changed using the ETag."
# This ONLY works because it's a GET request.

// HTTP 200 OK  ← says "everything is fine!"
// But wait...
{
  "ok": false,
  "error": "channel_not_found",
  "response_metadata": {
    "scopes": ["chat:write"]
  }
}

// The HTTP status says success.
// The body says failure.
// Your code has to parse the body to know what happened.
// Every error check looks like: if (!response.ok) ...

// HTTP 404 Not Found  ← tells you immediately
{
  "message": "Not Found",
  "documentation_url": "https://docs.github.com/..."
}

// HTTP 403 Forbidden  ← rate limited
{
  "message": "API rate limit exceeded for 1.2.3.4",
  "documentation_url": "https://docs.github.com/..."
}

// HTTP 422 Unprocessable Entity  ← bad input
{
  "message": "Validation Failed",
  "errors": [{"field": "title", "code": "missing"}]
}

// No ambiguity. The status code tells you what happened
// BEFORE you even parse the body.

// HTTP 402 Payment Required  ← card was declined
{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "decline_code": "insufficient_funds",
    "message": "Your card has insufficient funds.",
    "param": "source"
  }
}

// The status code (402) tells middleware & monitoring
// "this is a payment problem, not a server bug."
// The body tells the developer exactly what went wrong.
// Both layers carry meaning.

In the year 2000, a PhD student named Roy Fielding at UC Irvine was writing his doctoral dissertation. He'd been one of the principal authors of the HTTP specification — the protocol that makes the entire web work. His thesis, titled "Architectural Styles and the Design of Network-Based Software Architectures," had a chapter (Chapter 5) that would change how we build APIs forever. He called the idea REST — REpresentational State TransferThe full name is rarely used. What matters is the core idea: organize your API around resources (things, nouns) that clients interact with by transferring representations (usually JSON) of those resources' state. In plain English: "here's the data for user #42, as JSON.".

The key insight was deceptively simple: stop thinking in functions, start thinking in resources.

Here's what Fielding figured out. Instead of inventing a new URL for every action:

# BEFORE: The URL is a verb (what to DO)
/getUser?id=5         → GET  /users/5
/createOrder          → POST /orders
/updateProduct?id=3   → PUT  /products/3
/deleteAccount?id=7   → DELETE /accounts/7
/getUserOrders?id=5   → GET  /users/5/orders

# The URL is always a NOUN (the thing).
# The HTTP method is always the VERB (the action).
# This combination is so predictable that a developer
# can GUESS the API without reading docs.

Look what happened. Ten unique endpoint names with three different naming styles collapsed into three resource nouns with the same five verbs. A developer who's never seen your API can guess the endpoints. "I bet there's a GET /orders and a GET /orders/99." And they'd be right. That's the power of a convention — you learn the pattern once and apply it everywhere.

And this is exactly what the best real-world APIs do. Here's Stripe — widely considered the gold standardStripe's API is so well-designed that other companies use it as a reference when building their own. It follows REST conventions strictly: resources as nouns, proper HTTP methods, proper status codes, cursor-based pagination, and idempotency keys for safe retries. of API design:

# Creating a charge (real Stripe API call)
curl -X POST https://api.stripe.com/v1/charges \
  -u sk_test_xxx: \
  -d amount=2000 \
  -d currency=usd \
  -d source=tok_visa

# Response: HTTP 201 Created
# {
#   "id": "ch_1234",
#   "object": "charge",
#   "amount": 2000,
#   "currency": "usd",
#   "status": "succeeded"
# }

# Notice the design choices:
# - POST (creating a new charge) — not /createCharge
# - /v1/charges (noun, plural) — the resource
# - HTTP 201 (not 200) — "created", not just "ok"
# - Versioning via URL path (/v1/)
# - Auth via HTTP Basic (-u flag)

This is RESTREpresentational State Transfer — an architectural style for APIs defined by Roy Fielding in his 2000 PhD dissertation at UC Irvine. The key idea: organize your API around resources (nouns) and use standard HTTP methods (verbs) to manipulate them. The "representational state transfer" part means: the client sends and receives representations (usually JSON) of a resource's current state. — REpresentational State Transfer. Don't memorize that name. Just remember: the URL is always a noun (the thing), the HTTP method is always a verb (the action). That's the entire philosophy.

REST doesn't add any new technology. There's no library to install, no protocol to learn. It's purely a convention — an agreement about how to organize URLs and use HTTP methods in a predictable way. The same HTTP that loads web pages in your browser already speaks REST. You just need to use it properly.

REST is built on six core concepts. You already understand the main idea — resources as nouns, HTTP methods as verbs. Now let's go deeper into each building block so you can design APIs that are clean, consistent, and production-ready.

POST /books HTTP/1.1
Host: api.bookstore.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOi...

{
  "title": "Designing Data-Intensive Applications",
  "author": "Martin Kleppmann",
  "price": 45.99,
  "isbn": "978-1449373320"
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /books/143

{
  "id": 143,
  "title": "Designing Data-Intensive Applications",
  "author": "Martin Kleppmann",
  "price": 45.99,
  "isbn": "978-1449373320",
  "created_at": "2026-03-18T10:30:00Z"
}

GET /books/42 HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{ "id": 42, "title": "DDIA", "price": 45.99 }

You now know the fundamentals — resources, methods, status codes, headers. That's enough to build a working REST API. But a great API handles the hard stuff too: How do you change your API without breaking everyone? How do you return 10 million records? How do clients retry safely? Let's dig in.

Versioning — Changing Your API Without Breaking the World

Your API is live. Thousands of apps depend on it. Now you need to change the response format — maybe rename a field, or restructure the data. If you just change it, every client breaks. That's why APIs need versioningA strategy for evolving your API over time while maintaining backward compatibility. Old clients keep using v1, new clients use v2. You support both until everyone migrates. — a way to evolve without breaking existing users.

The industry favorite is URL path versioning — /v1/books, /v2/books. It's the simplest to understand, the easiest to route, and the most visible. Stripe, GitHub, and Twilio all use it. For most teams, this is the right choice. Don't overthink it.

Pagination — Returning a Million Records Without Crashing

Your bookstore has 2 million books. A client calls GET /books. Do you return all 2 million in one response? Of course not — that would be a 500MB JSON blob that takes 30 seconds to download and crashes the client's browser. You need paginationBreaking a large collection into smaller chunks ("pages") that clients can request one at a time. Like reading a book one chapter at a time instead of the whole thing at once. — breaking the results into pages.

GET /books?page=3&limit=20

Response:
{
  "data": [ ... 20 books ... ],
  "pagination": {
    "page": 3,
    "limit": 20,
    "total": 1847,
    "total_pages": 93
  }
}

GET /books?limit=20&after=eyJpZCI6MTAwfQ==

Response:
{
  "data": [ ... 20 books ... ],
  "pagination": {
    "next_cursor": "eyJpZCI6MTIwfQ==",
    "has_more": true
  }
}

Filtering & Sorting — Finding the Needle in the Haystack

Pagination gives you pages. But clients rarely want all books — they want science fiction books under $20, sorted by rating. That's filteringNarrowing down results based on criteria. In REST, filters are typically query parameters: /books?genre=sci-fi&max_price=20. The server applies these as WHERE clauses in the database query. and sortingOrdering results by a specific field. In REST: /books?sort=price (ascending) or /books?sort=-price (descending, with a minus prefix). Can sort by multiple fields: ?sort=-rating,price..

# Filter by genre AND price, sort by rating (descending)
GET /books?genre=sci-fi&max_price=20&sort=-rating&limit=20

# Filter by author, sort by publication date (newest first)
GET /books?author=kleppmann&sort=-published_at

# Search with a query string
GET /books?q=distributed+systems&in_stock=true

The conventions: use query parameters for filters, prefix with - for descending sort, use q for full-text search. Keep filter names consistent with your response field names — if the JSON says "genre": "sci-fi", the filter should be ?genre=sci-fi, not ?book_genre=sci-fi.

Idempotency Keys — Making Retries Safe

Here's a scary scenario. A client sends POST /orders to place an order. The server creates the order and charges the credit card. But the response never arrives — the network drops it. The client doesn't know if the order went through, so it retries. Without protection, the customer gets charged twice.

The solution is idempotency keysA unique ID that the client generates and sends with each request. If the server receives the same key twice, it returns the original response instead of processing the request again. Stripe popularized this pattern — every payment API uses it now.. The client generates a unique ID and sends it with the request. The server stores this ID alongside the result. If the same ID shows up again, the server returns the original response instead of processing the request a second time.

Stripe uses this for every payment. You send an Idempotency-Key header, and Stripe stores the result for 24 hours. If the same key appears again, Stripe returns the original result without charging the card again. This is such a critical pattern that it should be built into every API that processes money, creates resources, or triggers side effects.

Rate Limiting Headers — "You're Calling Too Much"

APIs need to protect themselves from clients that call too often — whether it's a bug in someone's code, a DDoS attack, or a script gone wild. Rate limitingRestricting how many requests a client can make in a given time window. E.g., "1000 requests per hour." When the limit is exceeded, the server returns 429 Too Many Requests. caps the number of requests per time window, and good APIs tell you exactly where you stand via headers.

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000        # Max requests per hour
X-RateLimit-Remaining: 847     # Requests left in this window
X-RateLimit-Reset: 1710761400  # When the window resets (Unix timestamp)

# When you hit the limit:
HTTP/1.1 429 Too Many Requests
Retry-After: 342               # Wait 342 seconds before retrying

Good clients check X-RateLimit-Remaining proactively and slow down before hitting the limit. The Retry-After header on a 429 response tells the client exactly when it's safe to try again — so it doesn't have to guess.

REST isn't the only way to build APIs. It's the most popular, but two other styles are widely used — and each one exists because REST can't solve every problem perfectly. Let's compare them honestly, without fanboyism.

Here's the practical truth: most companies use REST for public APIs and gRPC for internal service-to-service communication. GraphQL thrives when you have many different clients (mobile, web, third-party) that each need different slices of the same data. GitHub actually offers both — their REST API (v3) and GraphQL API (v4) coexist, and you pick whichever fits your use case.

# You just want the user's name. REST returns EVERYTHING:
GET /users/42

{
  "id": 42,
  "name": "Alice",           ← you wanted this
  "email": "alice@...",      ← didn't need this
  "avatar_url": "...",       ← or this
  "address": { ... },        ← definitely not this (1KB of data)
  "preferences": { ... }     ← or this
}

# GraphQL lets you ask for just what you need:
# { user(id: 42) { name } }  →  { "name": "Alice" }

# Step 1: Get the user
GET /users/42           → { "id": 42, "name": "Alice" }

# Step 2: Get their orders (separate call!)
GET /users/42/orders    → [ { "id": 1, ... }, { "id": 2, ... } ]

# Step 3: Get items for each order (5 MORE calls!)
GET /orders/1/items     → [ ... ]
GET /orders/2/items     → [ ... ]
...

# That's 7 round trips for one screen of data!

# GraphQL does it in ONE:
# { user(id:42) { name, orders { id, items { name } } } }

Theory is nice, but how do the world's best APIs actually work? Let's look at three APIs that are consistently rated among the best — and what specific choices they made that you can steal for your own designs.

Stripe — The API Every API Aspires to Be

Stripe processes billions of dollars in payments. Their API is so well-designed that it's become the gold standard for how REST APIs should work. Here's what they do right:

• Idempotency keys on every POST — send Idempotency-Key: abc-123 and Stripe stores the result for 24 hours. Retries are always safe. This is critical when you're moving money.
• Expand parameter — instead of making 3 API calls, use ?expand[]=customer&expand[]=invoice to include related objects inline. Solves the N+1 problem elegantly.
• Versioned via date — Stripe uses Stripe-Version: 2024-06-20 instead of /v1/. Each account is pinned to the version it was created with. You can upgrade at your own pace.
• Consistent error format — every error has type, code, message, and param (the field that caused it). Machine-readable AND human-readable.

// Stripe error response — clear, actionable, consistent
{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "message": "Your card was declined.",
    "param": "source",
    "decline_code": "insufficient_funds"
  }
}

GitHub — REST and GraphQL Living Together

GitHub is interesting because they offer both API styles. Their REST API (v3) has been around for years and is battle-tested. Their GraphQL API (v4) launched in 2017 to solve the over-fetching problem that mobile developers complained about.

• HATEOAS in practice — every response includes url links to related resources. A repo object contains issues_url, pulls_url, commits_url. You can navigate the entire API by following links.
• Pagination via Link headers — Link: </repos?page=3>; rel="next", </repos?page=50>; rel="last". Clients follow the links instead of constructing URLs.
• Conditional requests — ETag and If-None-Match for caching. If data hasn't changed, GitHub returns 304 Not Modified with zero body. Saves bandwidth and doesn't count against your rate limit.

Twilio — So Simple You Can Use It From curl

Twilio's design philosophy is radical simplicity. Sending an SMS is one API call. Making a phone call is one API call. They optimized for "time to first hello world" — a new developer should be able to send their first text message in under 5 minutes.

• Subresources for everything — /Accounts/{sid}/Messages, /Accounts/{sid}/Calls. The URL hierarchy mirrors the business domain.
• Human-readable SIDs — resource IDs start with a prefix that tells you what they are: AC for Account, SM for SMS, CA for Call. You can identify a resource type just by looking at its ID.
• Webhook-first design — when an SMS is delivered or a call ends, Twilio POSTs to your webhook URL with the status update. You don't have to poll.

REST is wonderful for most APIs. But it's not the answer to everything. Forcing REST onto problems it wasn't designed for leads to ugly, inefficient APIs. Here are the situations where you should reach for something else.

The last point is worth emphasizing. Purists insist that everything must be a noun. But POST /accounts/42/actions/merge is genuinely worse than POST /accounts/42/merge. The best APIs are pragmatic — they follow REST conventions where they fit and deviate where they don't. Stripe uses POST /charges/{id}/capture for capturing a payment. That's a verb, and it's fine.

These are the mistakes I see in code reviews, interviews, and production APIs. Each one seems minor, but at scale they compound into APIs that are painful to use.

{
  "error": {
    "code": "validation_error",
    "message": "Price must be a positive number",
    "field": "price",
    "value": -5.99
  }
}

REST API design comes up in two contexts: dedicated API design rounds ("Design an API for X") and as part of system design rounds ("Here's the architecture — now design the API layer"). Here's how to handle both.

The best way to learn REST API design is to practice it. These five challenges progress from beginner to expert. For each one, write down your endpoints before opening the solution. In interviews, you won't have answers to peek at — build that muscle now.

# Posts
GET    /posts              # List all posts (paginated)
GET    /posts/{id}         # Get single post
POST   /posts              # Create a post
PATCH  /posts/{id}         # Update a post
DELETE /posts/{id}         # Delete a post

# Comments (nested under posts)
GET    /posts/{id}/comments       # List comments on a post
POST   /posts/{id}/comments       # Add a comment
DELETE /posts/{id}/comments/{cid} # Delete a comment

# Likes (sub-resource of posts)
POST   /posts/{id}/likes          # Like a post
DELETE /posts/{id}/likes          # Unlike a post (your own)
GET    /posts/{id}/likes          # List who liked it

# Users
GET    /users/{id}         # Get user profile
GET    /users/{id}/posts   # Get a user's posts

# Product catalog (cursor pagination for 2M products)
GET /products?category=electronics&min_price=10&max_price=500
    &in_stock=true&sort=-rating&limit=20&after=eyJpZCI6MTAwfQ

# Response includes:
# { "data": [...], "pagination": { "next_cursor": "...", "has_more": true } }

GET /products/{id}          # Single product with full details
GET /products/{id}/reviews  # Reviews for a product

# Cart
GET    /carts/me            # Current user's cart
POST   /carts/me/items      # Add item: { "product_id": 42, "quantity": 2 }
PATCH  /carts/me/items/{id} # Update quantity: { "quantity": 5 }
DELETE /carts/me/items/{id} # Remove item from cart

# Checkout
POST /orders                # Convert cart to order: { "cart_id": "...", "payment_method": "..." }

// 422 Unprocessable Entity — invalid card
{ "error": { "type": "card_error", "code": "invalid_card_number",
  "message": "The card number is not a valid credit card number.",
  "param": "card_number" } }

// 402 Payment Required — insufficient funds
{ "error": { "type": "card_error", "code": "insufficient_funds",
  "message": "The card has insufficient funds.",
  "decline_code": "insufficient_funds" } }

// 429 Too Many Requests — rate limited
{ "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded",
  "message": "Too many requests. Retry after 60 seconds." } }
// + Retry-After: 60 header

// 401 Unauthorized — bad API key
{ "error": { "type": "authentication_error", "code": "invalid_api_key",
  "message": "The API key provided is invalid." } }

// 500 Internal Server Error — our fault
{ "error": { "type": "api_error", "code": "internal_error",
  "message": "An unexpected error occurred. Please retry.",
  "request_id": "req_abc123" } }

# Create a payment intent (requires Idempotency-Key)
POST /v1/payment-intents
Idempotency-Key: pi_unique_123
{ "amount": 2000, "currency": "usd", "payment_method": "pm_card_visa" }
→ 201 Created { "id": "pi_abc", "status": "requires_confirmation" }

# Confirm the payment (client-side SDK typically does this)
POST /v1/payment-intents/pi_abc/confirm
→ 200 { "status": "requires_action", "next_action": {
    "type": "redirect_to_url",
    "redirect_url": "https://bank.com/3ds?token=xyz" } }

# After 3DS, the status updates asynchronously via webhook:
# POST https://yourapp.com/webhooks/stripe
# { "type": "payment_intent.succeeded", "data": { "id": "pi_abc" } }

# Capture an authorized payment (for auth-then-capture flow)
POST /v1/payment-intents/pi_abc/capture
→ 200 { "status": "succeeded", "amount_captured": 2000 }

# Refund (full or partial)
POST /v1/refunds
{ "payment_intent": "pi_abc", "amount": 500 }
→ 201 { "id": "re_xyz", "status": "pending", "amount": 500 }

# List refunds for a payment
GET /v1/payment-intents/pi_abc/refunds

Everything from this page on one screen. Pin this for your next API design session or interview prep.

GET    → Read (safe, idempotent)
POST   → Create (NOT idempotent)
PUT    → Replace (idempotent)
PATCH  → Partial update
DELETE → Remove (idempotent)

Safe = doesn't change data
Idempotent = same result if repeated

200 OK           → Success
201 Created      → POST success
204 No Content   → DELETE success
400 Bad Request  → Invalid input
401 Unauthorized → Bad/missing auth
403 Forbidden    → No permission
404 Not Found    → Bad URL / no data
409 Conflict     → Duplicate/state err
422 Unprocessable→ Validation failed
429 Too Many Req → Rate limited
500 Server Error → Our fault

Nouns, not verbs:
  /users NOT /getUsers

Plurals:
  /books NOT /book

Lowercase + hyphens:
  /order-items NOT /orderItems

Nesting for relationships:
  /users/42/orders

Max 3 levels deep:
  /users/42/orders/99/items ← OK
  /.../items/3/details ← too deep

Offset (simple, slow at depth):
  ?page=3&limit=20

Cursor (fast, no jump-to-page):
  ?limit=20&after=eyJpZCI6MTAwfQ

Response includes:
  "next_cursor": "..."
  "has_more": true

Rule: cursor for feeds/search,
offset for admin dashboards

URL path (most common):
  /v1/books  →  /v2/books

Header:
  API-Version: 2

Query param:
  /books?version=2

Best practice:
  URL path (Stripe, GitHub, Twilio)
  Support old version for 6-12 months
  Deprecation headers + sunset date

{
  "error": {
    "type": "validation_error",
    "code": "invalid_email",
    "message": "Email is invalid",
    "field": "email"
  }
}

Always include:
  - Machine-readable code
  - Human-readable message
  - Which field caused it
  - Request ID for debugging

REST API design connects to almost every other system design topic. Here's how what you learned feeds into the rest of your learning journey.