REST API Best Practices

1. Use Nouns for Resources

URLs identify resources, not actions. Use plural nouns.

✅ GET /users /products/42
❌ 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

3. Consistent HTTP Status Codes

OK         — success (GET, PUT, PATCH)
Created    — resource created (POST)
No Content — success, no body (DELETE)
Bad Request — invalid input
Unauthorized — missing/invalid auth
Forbidden  — no permission
Not Found  — resource doesn't exist
Unprocessable — validation failed
Server Error — internal error

4. Versioning

Version your API to avoid breaking changes.

✅ /api/v1/users
✅ 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

6. Use JSON for Request/Response Bodies

Always set Content-Type: application/json. Return consistent error objects with code, message, and details fields.