Resources, Methods & Status Codes

Nouns, Not Verbs

GET    /users          list users
POST   /users          create a user
GET    /users/123      fetch user 123
PUT    /users/123      replace user 123 entirely
PATCH  /users/123      partially update user 123
DELETE /users/123      delete user 123

# nested for ownership, avoid going too many levels deep
GET    /posts/123/comments

URLs represent resources (nouns), not actions (verbs) — the HTTP method expresses the action. Plural collection names read naturally for both the list and single-item form. PUT expects the full resource; PATCH expects only changed fields.

Idempotency

GET, PUT, DELETE are idempotent — repeating the same request leaves the system in the same end state, making them safe to retry after a network timeout. POST is not — retrying it can create a duplicate resource.

Status Codes

201 Created         -> POST succeeded, new resource made (often with a Location header)
200 OK              -> successful GET/PUT/PATCH
204 No Content      -> successful DELETE, nothing to return
400 Bad Request     -> malformed/invalid request
401 Unauthorized    -> missing/invalid auth
404 Not Found
429 Too Many Requests
500 Internal Server Error

Returning 200 with an error buried in the JSON body is a common anti-pattern — use the specific status code so clients can react programmatically without parsing the body first.

Error Response Shape

{
  "error": "validation_failed",
  "message": "Email is invalid",
  "fields": { "email": "invalid format" }
}