Designing REST APIs that age well

An API is a contract. The easier it is to guess the next endpoint, the less documentation you need and the fewer mistakes your clients make.

Model resources, not actions

Name endpoints after the things they expose, then let HTTP methods describe what happens to them.

• GET /invoices — list invoices.
• POST /invoices — create one.
• GET /invoices/{id} — read one.
• PATCH /invoices/{id} — update part of one.
• DELETE /invoices/{id} — remove one.

Be predictable with status codes

• 200 for a successful read, 201 for a successful create.
• 204 for a successful delete with no body.
• 400 for invalid input, 401 for missing auth, 403 for denied access.
• 404 for something that does not exist, 409 for a conflict.

Pagination, filtering and errors

Return a consistent envelope so clients can parse every list the same way, and keep error bodies structured rather than free text.

{
  "data": [/* ... */],
  "page": 1,
  "pageSize": 20,
  "total": 137
}

Add filters and sorting as query parameters, and version only when you must break the contract. Most changes can be additive.