Designing REST APIs

An API (application programming interface) is the set of URLs your backend offers to other programs. REST is a popular style for designing them over HTTP. REST is a set of conventions, not a library: if you follow them, any developer can guess how your API works without reading a manual.

The core idea: your API is a collection of resources (things like menu items and orders). Each resource has a URL. You use standard HTTP methods to act on it. You have seen the methods and status codes in *HTTP in depth*; here we apply them.

A resource is a noun. The URL names the noun; the method is the verb. So we do not write /getMenu or /createOrder. We write GET /menu and POST /orders.

Not every action is a clean CRUD operation. Changing an order's status is a good example. The Brew & Bean API uses PATCH /orders/{id}/status, a sub-resource that stands for one part of the order with its own rules (only received → preparing → ready → picked_up is allowed). For real actions that do not fit, use a verb sub-path with POST, for example POST /orders/42/cancel, and keep it rare.

{
  "customer_name": "Asha",
  "phone": "9876543210",
  "items": [
    {"item_id": "cappuccino", "qty": 1},
    {"item_id": "croissant", "qty": 2}
  ],
  "pickup_time": "2026-11-02T09:30:00+05:30"
}

The client sends ids and quantities only. It never sends prices or totals.

{
  "id": 42,
  "customer_name": "Asha",
  "phone": "9876543210",
  "items": [
    {"item_id": "cappuccino", "qty": 1},
    {"item_id": "croissant", "qty": 2}
  ],
  "total": 480,
  "status": "received",
  "pickup_time": "2026-11-02T09:30:00+05:30",
  "created_at": "2026-11-02T08:55:12+05:30"
}

The total is 180 + 2 x 150 = 480, computed by the server. Use ISO 8601 for dates and keep the format identical across the API.

A list endpoint that returns everything breaks once you have 100,000 orders. Let clients narrow and page the results using query parameters.

{
  "items": [ {"id": 42, "status": "ready"}, {"id": 41, "status": "ready"} ],
  "page": 1,
  "limit": 20,
  "total": 57
}

Always set a default and a maximum limit on the server (for example 20 and 100).

Page numbers are simple but can skip or repeat rows when new data arrives while the client is paging. Cursor pagination ("give me 20 orders after id 42") is steadier and faster on big tables. Start with page and limit; move to cursors when you need to.

Clients need to show a helpful message and decide what to do next. Pick one error shape and use it for every error.

{
  "error": {
    "code": "validation_error",
    "message": "One or more fields are invalid.",
    "details": [
      {"field": "items[0].qty", "message": "Must be at least 1"},
      {"field": "phone", "message": "Must be a 10-digit number"}
    ]
  }
}

A machine-readable code, a human-readable message, and per-field details.

Once a mobile app is in users' hands, you cannot force everyone to update. If you rename a field or change a response shape, old apps break. Two ways to stay safe:

- Additive changes are fine: adding a new field or a new endpoint does not break clients. Clients should ignore fields they do not know. - Breaking changes need a new version: put it in the path (/v1/orders, then /v2/orders) and keep v1 running until clients move. Path versioning is the simplest to understand and test.

Some teams use GraphQL (the client asks for exactly the fields it wants) or gRPC (fast binary calls between services). They are covered in *GraphQL and gRPC: other API styles*. REST remains the default for public and web APIs, and the most asked about in interviews.

Expect: "Design the endpoints for a library / to-do app / e-commerce cart". A strong answer lists the resources, uses plural nouns and the right methods, shows the status codes, covers pagination and an error format, and mentions authentication. Others: "What makes an API RESTful?" (resources, standard methods, stateless requests, consistent representations), "PUT versus PATCH", and "How do you version an API?"

You are a senior backend engineer reviewing an API design. Here is my design for [app, e.g. a library system]:

---
[list your endpoints with method, path, request and response]
---

Review it against REST conventions: resource naming, correct methods and status codes, pagination, error format and versioning. List problems in order of importance and show the corrected endpoint list as a table.

What to expect: Check that the answer notices verbs in URLs, wrong status codes and missing pagination, and then confirm each suggestion makes sense for your app.