RESTful API Design Principles for System Design
On this page
What is a RESTful API?
An API outlives the code behind it. Mobile apps that will never update, partner integrations and other teams' services all depend on its URLs, methods and responses. REST (Representational State Transfer) is a set of conventions that make HTTP APIs predictable, so clients can guess how they behave and caches and proxies can help.
REST API design rules
- Resources are nouns at URLs:
/orders,/orders/42,/customers/7/orders. - HTTP methods are the verbs:
GETreads,POSTcreates,PUTreplaces,PATCHupdates part,DELETEremoves. - Status codes mean something: clients, monitoring and retries all rely on them.
- Stateless: each request carries everything needed to handle it, usually an auth token. The server keeps no per-client session between requests.
Worked example: an orders API and its status codes
GET /api/v1/orders?status=open&limit=20 200 OK, a page of orders
GET /api/v1/orders/42 200 OK, or 404 Not Found
POST /api/v1/orders 201 Created, Location: /api/v1/orders/43
PATCH /api/v1/orders/42 {"status":"cancelled"} 200 OK, or 409 Conflict if already shipped
DELETE /api/v1/orders/42 204 No ContentThe status codes worth getting right:
| Code | Use it for |
|---|---|
| 200 OK | Successful read or update with a body |
| 201 Created | POST created something; include its URL in Location |
| 204 No Content | Success with nothing to return |
| 400 Bad Request | The request is malformed or invalid |
| 401 Unauthorized | No valid credentials |
| 403 Forbidden | Authenticated, but not allowed |
| 404 Not Found | The resource doesn't exist |
| 409 Conflict | Valid request, but it conflicts with current state |
| 429 Too Many Requests | Rate limit exceeded (Day 20) |
| 500 / 503 | Server error / temporarily unavailable |
A common mistake is returning 200 with {"error": ...} in the body. Monitoring counts it as success, and retry logic never fires.
Give errors a consistent body too. Problem Details (RFC 9457) is the standard shape: type, title, status, detail, plus your own fields. ASP.NET Core produces it with AddProblemDetails(), so clients parse every error the same way.
Cancelling an order could also be POST /orders/42/cancel. Purists prefer the PATCH, but an action endpoint is fine when the action has its own rules and side effects. Be consistent across the API.
Idempotency keys: making POST safe to retry
Networks fail mid-request, so clients retry. GET, PUT and DELETE are idempotent: doing them twice has the same effect as once. POST isn't; retrying a "create order" can create two orders. The standard fix is an idempotency key: the client sends a unique Idempotency-Key header, and the server stores the result for that key and returns it again on a retry instead of creating a duplicate. Stripe's API popularized this; Day 65 covers it in depth.
Preventing lost updates with ETags
Alice and Bob both load order 42. Alice changes the address and saves. Bob changes the quantity and saves with the address he loaded, overwriting Alice's change. Nobody sees an error. That's a lost update.
HTTP has a built-in fix. The server returns an ETag, a version of the resource. The client sends it back in If-Match when it updates. If the resource changed in between, the server refuses with 412 Precondition Failed, and the client reloads:
GET /api/v1/orders/42 200 OK, ETag: "v7"
PATCH /api/v1/orders/42 If-Match: "v7" 200 OK, ETag: "v8"
PATCH /api/v1/orders/42 If-Match: "v7" 412 Precondition Failed (Bob's stale write)In SQL Server, a rowversion column makes a natural ETag, and EF Core uses it as a concurrency token.
Statelessness, versioning and pagination
Stateless means the server stores no session for the client between requests. Any instance behind the load balancer can handle any request, which is what makes horizontal scaling work (Day 2). The token in the Authorization header identifies the caller every time.
Versioning protects clients from breaking changes. The common choice is a version in the path, /api/v1/.... Adding a field is usually safe; removing or renaming one, or changing its meaning, needs a new version, kept alongside the old one for a published period. Day 55 goes deeper.
Pagination belongs in the design from day one: return a limited page and a cursor for the next one. A list endpoint that returns everything works until a customer has 200,000 orders. Prefer a cursor ("orders after id 9120") over ?page=500: an offset makes the database read and discard every earlier row, and inserts shift the pages so clients skip or repeat items.
Check yourself
The first request may have succeeded, so the retry creates a duplicate order. Accept an idempotency key and return the stored result for repeated keys.
Clients, caches, gateways and monitoring all read the status code first and treat a 200 as success, so the failure is invisible to them and errors don't appear on dashboards. Return 404, with a body that explains the problem, so the meaning is carried where every tool looks.
Return an ETag with each read and require If-Match on updates. A stale update gets 412 Precondition Failed instead of overwriting newer data.
Use 400 for requests that are malformed, such as invalid JSON or a missing required field. Use 422 for requests that are well formed but break a business rule, such as an end date before the start date. Consistency matters more than the exact choice, so document it.
Page numbers with offsets get slower deep in a list and skip or repeat items when rows are inserted or deleted between requests. A cursor based on the last item's sort key continues exactly where the previous page ended and stays fast at any depth.