REST API Design Best Practices: URLs, Methods and Status Codes

A well-designed REST API is predictable: once a developer has used one endpoint, they can guess how the others work. These conventions get you most of the way there.

URLs name resources, not actions

GET    /orders              list orders
POST   /orders              create an order
GET    /orders/42           get one order
PATCH  /orders/42           update some fields
DELETE /orders/42           delete it
GET    /orders/42/items     items belonging to order 42

Avoid:  POST /createOrder,  GET /getOrderById?id=42

• Use plural nouns: /users, not /user.
• Lowercase with hyphens: /shipping-addresses.
• Nest only one level for clear ownership; deeper paths get unwieldy.
• For actions that don't fit CRUD, a sub-resource reads well: POST /orders/42/cancel.

Methods have meanings

• GET - read; safe and cacheable, never changes data.
• POST - create, or trigger a process.
• PUT - replace a whole resource (idempotent).
• PATCH - change some fields.
• DELETE - remove (idempotent).

Status codes worth using

200 OK                 successful read/update
201 Created            + Location header pointing at the new resource
204 No Content         successful delete
400 Bad Request        malformed request
401 Unauthorized       not authenticated
403 Forbidden          authenticated but not allowed
404 Not Found          doesn't exist (or you may not know it exists)
409 Conflict           duplicate, version conflict
422 Unprocessable      validation failed
429 Too Many Requests  rate limited
500 Internal Error     our fault

Filtering, sorting and fields

GET /orders?status=shipped&created_after=2026-01-01&sort=-created_at&limit=20

Consistency beats cleverness

• Pick one case style for JSON fields (camelCase or snake_case) and use it everywhere.
• Use ISO 8601 timestamps in UTC: "2026-10-11T09:30:00Z".
• Return the same error shape from every endpoint.
• Represent money as integer minor units (paise, cents) or strings, never floats.