Catalog My learning Blog
System Design Roadmap: 100-Day Course for Engineers · Phase 2 · Lesson 14 · 5 min read

RESTful API Design Principles for System Design

On this page
  1. What is a RESTful API?
  2. REST API design rules
  3. Worked example: an orders API and its status codes
  4. Idempotency keys: making POST safe to retry
  5. Preventing lost updates with ETags
  6. Statelessness, versioning and pagination
  7. Check yourself

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: GET reads, POST creates, PUT replaces, PATCH updates part, DELETE removes.
  • 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.
A resource-oriented API: nouns as URLs, verbs as HTTP methods, and status codes that carry meaning.
A resource-oriented API: nouns as URLs, verbs as HTTP methods, and status codes that carry meaning.

Worked example: an orders API and its status codes

Code
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 Content

The status codes worth getting right:

CodeUse it for
200 OKSuccessful read or update with a body
201 CreatedPOST created something; include its URL in Location
204 No ContentSuccess with nothing to return
400 Bad RequestThe request is malformed or invalid
401 UnauthorizedNo valid credentials
403 ForbiddenAuthenticated, but not allowed
404 Not FoundThe resource doesn't exist
409 ConflictValid request, but it conflicts with current state
429 Too Many RequestsRate limit exceeded (Day 20)
500 / 503Server 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:

Code
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.