RESTful API design has genuine conventions worth following, not because REST is a strict, formal standard, but because consistency makes an API dramatically easier for other developers to predict and use correctly.
# Use nouns for resources, HTTP methods for actions - not verbs in the URL GET /api/orders - list orders GET /api/orders/123 - get one order POST /api/orders - create a new order PUT /api/orders/123 - replace an order entirely PATCH /api/orders/123 - partially update an order DELETE /api/orders/123 - delete an order # NOT this - verbs in the URL, ignoring HTTP methods entirely GET /api/getOrder?id=123 POST /api/deleteOrder
Status Codes That Actually Mean Something
- 200 — success, with a response body
- 201 — successfully created, typically includes a
Locationheader pointing to the new resource - 204 — success, deliberately no response body (a common choice for DELETE)
- 400 — client error, malformed request
- 401 vs 403 — genuinely distinct: 401 means “we don’t know who you are,” 403 means “we know who you are, and you’re not allowed”
- 422 — the request was well-formed, but semantically invalid (failed validation)
Consistent, predictable naming and status code usage means a developer integrating with your API can correctly guess the shape of an endpoint they haven’t even read the documentation for yet — genuinely valuable, and worth the discipline of following convention even when a slightly different approach might seem locally more convenient.