Skip to content
learn
  1. Learn
  2. High Level System Design
  3. APIs and Communication

System Design HLD-03.01

REST API design

Resources and URLs, HTTP methods and idempotency, status codes, filtering and sorting, error bodies and versioning: how to design a predictable REST API.

Beginner 15 min Last reviewed

The big idea

An API is a contract between a service and everyone who calls it. RESTRepresentational State Transfer: a style of API design that models data as resources identified by URLs and manipulated with standard HTTP methods. is the most common style for web APIs because it reuses what HTTP already provides. Instead of inventing an operation for everything (getUserOrders, createOrderForUser, cancelOrderNow), you model your data as resources with addresses, and use the same small set of HTTP methods on all of them.

The payoff is predictability. A developer who has seen GET /users/42 can guess GET /users/42/orders without reading the docs. Caches, proxies, browsers and monitoring tools already understand HTTP methods and status codes, so a well-designed REST API gets caching, retries and observability almost for free. A badly designed one confuses every client that touches it, and an API, once published, is very hard to change.

Think of a library. Every book has a shelf address, and a few standard actions apply to any of them: look at it, add a new one, replace it, remove it. You do not need a different form for every book.

How it works

Step 1: Resources are nouns with addresses

A resourceAny thing the API exposes, such as a user, an order or a collection of orders, identified by a URL. is a thing: a user, an order, a list of orders. Each one has a URL. Collections are plural nouns and single items are addressed by id:

A REST resource tree with one request mapped to its handler A tree of URLs: /users, /users/{id}, /users/{id}/orders and /users/{id}/orders/{orderId}. A request GET /users/42/orders glows along the path to the orders collection and then to the handler listOrders(userId=42). GET /users collection /users/42 one user /users/42/orders collection /users/42/profile sub-resource /orders/7 one order listOrders(42) handler Figure 1. Resources form a tree of nouns. The request GET /users/42/orders walks the tree to the orders collection of user 42, and the router hands it to one handler.

Good habits: plural nouns (/orders, not /getOrder), lowercase with hyphens (/order-items), and nesting only where the child truly belongs to the parent and only one or two levels deep. An order can also live at /orders/7 directly, which is simpler for clients that already know its id.

Step 2: Methods are verbs, with guarantees

MethodMeaningSafeIdempotent
GETread a resource or collectionyesyes
POSTcreate a new item in a collection, or run an actionnono
PUTreplace a resource completelynoyes
PATCHchange some fieldsnonot guaranteed
DELETEremove a resourcenoyes

A safeA method that does not change server state, so it can be cached, prefetched and retried freely. method has no side effects. An idempotentAn operation that has the same effect whether it is performed once or many times. method can be repeated without changing the outcome beyond the first call. These are not just definitions: proxies and clients rely on them. A browser may prefetch a GET link and a load balancer may retry a GET after a timeout. If your GET deletes something, those tools will delete it for you. POST is the dangerous one to retry, which Idempotency and safe retries solves.

Step 3: Status codes and error bodies

Return the status code that matches what happened (from HTTP/1.1, HTTP/2 and HTTP/3 ), and give errors a consistent machine-readable body:

{
  "error": {
    "code": "insufficient_funds",
    "message": "The card has insufficient funds.",
    "request_id": "req_8f2c1"
  }
}

Clients branch on the stable code, show the human message, and quote the request_id to support so you can find the logs.

Step 4: Filtering, sorting, paging and versioning

Collections take query parameters rather than new endpoints: GET /orders?status=paid&sort=-created_at&limit=20. Large collections must be paged, covered in Pagination patterns .

APIs change, and clients you do not control will break if fields disappear. Three common versioning strategies:

  • In the URL: /v1/orders. Visible, easy to route, the most common choice for public APIs.
  • In a header: Accept: application/vnd.example.v2+json or a date-based version header. Keeps URLs clean; harder to test in a browser.
  • No versions, only additive changes: add fields, never remove or rename. Works well internally with discipline.

Whatever you choose, adding a field is safe; removing, renaming or changing the meaning of one is a breaking change.

Try it

This interactive needs JavaScript. The diagrams and text above cover the same idea.

Try this:

  1. Compare GET, PUT and DELETE on /users/42. Which ones could a client safely retry after a timeout?
  2. Try POST /users/42. Why does the API refuse, and which path should you POST to instead?
  3. Try DELETE /users/99. Should a client that retried a delete and got 404 treat it as an error?

Going deeper

HATEOAS, briefly

Strict REST includes HATEOAS: responses contain links telling the client what it can do next ("cancel": "/orders/7/cancel"), so clients follow links instead of building URLs. It is elegant and rarely fully implemented; most real APIs include a few links, such as the next page, and document the rest.

When an action is not a resource

Some operations are verbs: "send this invoice", "retry this payment". You can model them as a sub-resource (POST /invoices/9/send) or as creating a resource (POST /payment-retries). Both are fine; pick one style and use it everywhere. When an API is mostly actions, gRPC or GraphQL, in gRPC and Protocol Buffers and GraphQL , may fit better.

Trade-offs

OptionWins whenLoses when
REST Public and partner APIs, CRUD-shaped data, anything that benefits from HTTP caching and tooling Clients that need many related objects in one call, or very chatty internal traffic
Version in the URL Public APIs: obvious, easy to route and to deprecate Clean URLs and gradual per-field evolution
Additive-only changes, no versions Internal APIs with good discipline and tests Situations where you truly must remove or redefine a field

Common mistakes

  • Verbs in URLs (/getUser, /createOrder), which duplicates what the method already says.
  • GET requests that change data, which crawlers, prefetchers and retries will trigger by accident.
  • Returning 200 OK with an error inside the body, so monitoring counts failures as successes.
  • Renaming or removing a field without a new version, breaking every client that used it.
  • Unbounded collections with no paging. They work in development and time out in production.

Check yourself

  1. Which URL follows REST conventions best for one order of user 42?

    Show answer

    B. /users/42/orders/7 Plural nouns, ids in the path, and the HTTP method expresses the action.

  2. Which method is idempotent but not safe?

    Show answer

    C. PUT PUT changes state (not safe), but repeating the same PUT leaves the same result (idempotent). DELETE is the same.

  3. A client sends malformed JSON. What should the API return?

    Show answer

    B. 400 Bad Request with an error body It is the client's mistake, so a 4xx code with a clear, machine-readable error body.

  4. Which change can break existing clients?

    Show answer

    C. Renaming an existing field Clients that read the old field name will stop working; additive changes are safe.

Recap

  • Model data as resources: plural nouns with ids, nested at most a level or two.
  • Use HTTP methods as verbs, and respect their safety and idempotency.
  • Return accurate status codes and a consistent, machine-readable error body.
  • Filter, sort and page collections with query parameters.
  • Version deliberately; adding fields is safe, removing or renaming them is not.

Get new lessons by email

Get new posts on backend and AI internals. No spam, unsubscribe anytime.

Your email is only used to send new posts. Privacy

Next up