REST API Best Practices
1. Use Nouns for Resources
URLs identify resources, not actions. Use plural nouns.
✅ GET /users /products/42
❌ GET /getUser /fetchProduct
❌ GET /getUser /fetchProduct
2. HTTP Methods Semantics
Use the right verb for each operation.
GET /users — list all users
POST /users — create a user
GET /users/1 — get user #1
PUT /users/1 — replace user #1
PATCH /users/1 — partial update
DELETE /users/1 — delete user #1
POST /users — create a user
GET /users/1 — get user #1
PUT /users/1 — replace user #1
PATCH /users/1 — partial update
DELETE /users/1 — delete user #1
3. Consistent HTTP Status Codes
200 OK — success (GET, PUT, PATCH)
201 Created — resource created (POST)
204 No Content — success, no body (DELETE)
400 Bad Request — invalid input
401 Unauthorized — missing/invalid auth
403 Forbidden — no permission
404 Not Found — resource doesn't exist
422 Unprocessable — validation failed
500 Server Error — internal error
201 Created — resource created (POST)
204 No Content — success, no body (DELETE)
400 Bad Request — invalid input
401 Unauthorized — missing/invalid auth
403 Forbidden — no permission
404 Not Found — resource doesn't exist
422 Unprocessable — validation failed
500 Server Error — internal error
4. Versioning
Version your API to avoid breaking changes.
✅ /api/v1/users
✅ Accept: application/vnd.myapi.v2+json
✅ Accept: application/vnd.myapi.v2+json
5. Pagination, Filtering, Sorting
GET /users?page=2&limit=20
GET /products?sort=price&order=asc
GET /orders?status=pending&userId=42
GET /products?sort=price&order=asc
GET /orders?status=pending&userId=42
6. Use JSON for Request/Response Bodies
Always set Content-Type: application/json. Return consistent error objects with code, message, and details fields.