REST API Design Best Practices

REST's core principles (in plain words)

Roy Fielding described REST in his 2000 PhD dissertation. REST is a set of design rules, not a product. The main ideas:

• Client–server: the client (frontend) and the server (backend) are separate. Each can change on its own.
• Stateless: each request carries everything the server needs (like an auth token). The server does not remember earlier requests. This makes horizontal scaling easy, because any server can answer any request (lesson 7).
• Cacheable: responses say whether a copy can be saved and reused (a cache). See lessons 14 to 16.
• Uniform interface: every API looks alike. Resources have URLs, you use standard methods, and data comes in a standard format (usually JSON, a text format for data).
• Layered system: the client does not need to know if there are proxies, gateways or CDNs in between (lesson 13).

1. Model resources with nouns

Rules of thumb:

• Use plural nouns for collections: /users, /orders.
• Use IDs for single items: /orders/5521.
• Nest to show ownership, but only one or two levels: /users/42/orders ✅. /users/42/orders/5521/items/3/reviews ❌ is too deep. Use /order-items/3/reviews or a filter instead.
• Use lowercase, hyphen-separated paths: /shipping-addresses.

What about actions that are not CRUD? CRUD means Create, Read, Update, Delete. "Cancel an order" or "send a password reset" do not fit these methods well. Two common approaches:

POST /orders/5521/cancel      (an action sub-resource: pragmatic and common)POST /password-resets         (model the action as creating a resource)

2. Use HTTP methods correctly

Idempotent means that doing the same request many times has the same effect as doing it once. It matters because a client can safely retry an idempotent request after a network error. Example: deleting order 7 twice still leaves order 7 deleted.

Never change data with GET. Browsers, crawlers and caches assume GET is safe and may call it at any time.

3. Return meaningful status codes

A status code is a number in the HTTP response that tells the client what happened. (See lesson 3 for the full list.) These are the ones every API should use correctly:

200 OK             – success with a body201 Created        – new resource; Location: /orders/5521202 Accepted       – will be processed later (async)204 No Content     – success, nothing to return400 Bad Request    – malformed input401 Unauthorized   – not logged in / bad token403 Forbidden      – logged in, but not allowed404 Not Found      – no such resource (or hidden for privacy)409 Conflict       – clashes with current state422 Unprocessable  – valid JSON, fails business validation429 Too Many Req.  – rate limited; include Retry-After500 / 503          – server-side problems

4. Consistent error responses

Every error should have the same shape, with a code that programs can read and a message that people can read. There is a standard for this called Problem Details (RFC 9457, a document that defines an error format for HTTP APIs):

HTTP/1.1 422 Unprocessable ContentContent-Type: application/problem+json{  "type": "https://api.shop.com/errors/insufficient-stock",  "title": "Insufficient stock",  "status": 422,  "detail": "Only 2 units of product 991 are available.",  "instance": "/orders",  "errors": [{ "field": "items[0].quantity", "message": "max 2" }]}

• Clients (the programs that call the API) can choose what to do based on the type (or a code field).
• Humans can read detail.
• Never show stack traces (the list of code lines where an error happened) or other internal details in production errors.

5. Filtering, sorting, searching and field selection

A query parameter is a name=value pair after the ? in a URL. Use query parameters on collections:

GET /products?category=shoes&brand=nike&min_price=1000&max_price=5000GET /products?sort=-created_at            (minus = descending)GET /products?q=running+shoes             (search)GET /products?fields=id,name,price        (only these fields)GET /orders?status=pending&created_after=2027-01-01

Lists should always be paginated. Pagination means sending the data in small pages. Never return "all orders" at once (covered in lesson 34).

6. Design request and response bodies well

• Use JSON with consistent names, either snake_case or camelCase. Pick one and keep to it.
• Use ISO 8601 (the international date and time format) with a time zone: "2027-01-11T09:30:00Z".
• Represent money as integers in the smallest unit (129900 paise) or as decimal strings ("1299.00"), plus a currency. Never use floats for money. A float is a number type that cannot store many decimals exactly (for example 0.1 + 0.2 is not exactly 0.3).
• Use stable string IDs for resources. Stable means the ID never changes.
• Use enums as strings ("status": "shipped") rather than magic numbers. An enum is a fixed list of allowed values.
• Do not show database internals (like column names such as usr_tbl_fk) in the API. The API is a contract, not a copy of your tables.

7. Use HTTP features you get for free

An ETag is a response header that holds a version label for a resource. A client can send it back later to ask "has this changed?" or "update only if it is still this version". The diagram shows optimistic concurrency: you do not lock the data. Instead you check the version when you save, and you reject the save if someone else changed it first.

• Caching: add Cache-Control (how long a copy may be reused) and ETag to GET responses (lessons 3 and 14).
• Conditional updates: clients send If-Match: "<etag>" on PUT or PATCH. If someone else changed the resource first, return 412 Precondition Failed. This is optimistic concurrency (lesson 21) over HTTP.
• Compression: gzip or Brotli make responses smaller, so they travel faster.
• Content negotiation: the client says which format it wants with Accept, and the server says which one it sends with Content-Type.

8. Security basics

• Always use HTTPS (HTTP with encryption, so others cannot read or change the data on the way).
• Put tokens in the Authorization header, never in URLs. URLs are saved in logs and browser history.
• Check authorisation for every object. Authorisation means checking what a user is allowed to do. A user who is logged in (authenticated) may still not be allowed to read /orders/5521. This is the top API vulnerability in the OWASP API Security list. It is called IDOR (insecure direct object reference) or broken object-level authorisation. More in Part 9.
• Validate all input (check it is the right type and size), and limit request sizes.
• Apply rate limits (a cap on how many requests a client can make), returning 429 with Retry-After (Part 7).
• Configure CORS (Cross-Origin Resource Sharing, the browser rule about which websites may call your API) carefully for browser clients (lesson 3).

9. Document and design the contract first

OpenAPI (formerly called Swagger) is a standard file format that describes a REST API: its URLs, inputs and outputs. You write it in YAML or JSON:

paths:  /orders/{id}:    get:      summary: Get an order      parameters:        - name: id          in: path          required: true          schema: { type: string }      responses:        "200": { description: The order }        "404": { description: Not found }

From one OpenAPI file you can generate:

• interactive documentation,
• client SDKs (ready-made code libraries for calling the API),
• server stubs (empty server code with the right shape),
• mock servers (fake servers that return sample answers),
• contract tests (tests that check the API follows the spec).

Many teams write the spec before the code. This is called "design-first". It lets the frontend and backend teams work at the same time.

10. REST maturity: how "RESTful" do you need to be?

The Richardson Maturity Model describes levels:

• Level 0: one endpoint, and everything is POST (like old SOAP or RPC over HTTP). RPC means calling a remote function by name.
• Level 1: separate resources (URLs).
• Level 2: proper HTTP methods and status codes. ← most good real-world APIs are here.
• Level 3: HATEOAS: responses include links to the next possible actions ("cancel": {"href": "/orders/5521/cancel"}), so clients can discover what to do next.

Level 3 is elegant, but few APIs use it fully. Level 2, done consistently, is the practical goal.