REST API Design
Design RESTful APIs with proper conventions and developer experience.
Resource Naming
Good - nouns, plural, hierarchical
GET /api/users GET /api/users/123 GET /api/users/123/orders POST /api/users PATCH /api/users/123 DELETE /api/users/123
Bad - verbs, actions in URL
GET /api/getUsers POST /api/createUser POST /api/users/123/delete
HTTP Methods
Method Purpose Idempotent
GET Read resource Yes
POST Create resource No
PUT Replace resource Yes
PATCH Partial update Yes
DELETE Remove resource Yes
Status Codes
Code Meaning Use For
200 OK Successful GET, PATCH
201 Created Successful POST
204 No Content Successful DELETE
400 Bad Request Validation errors
401 Unauthorized Missing auth
403 Forbidden Insufficient permissions
404 Not Found Resource doesn't exist
429 Too Many Requests Rate limited
Response Format
{ "data": { "id": "123", "type": "user", "attributes": { "name": "John", "email": "john@example.com" } }, "meta": { "requestId": "req_abc123" } }
Collection Response
{ "data": [...], "pagination": { "page": 1, "limit": 20, "total": 150, "totalPages": 8 }, "links": { "self": "/api/users?page=1", "next": "/api/users?page=2" } }
Query Parameters
GET /api/products?category=electronics # Filtering GET /api/products?sort=-price,name # Sorting GET /api/products?page=2&limit=20 # Pagination GET /api/products?fields=id,name,price # Field selection
Best Practices
-
Use nouns for resources, not verbs
-
Version API via URL path (/api/v1/ )
-
Return appropriate status codes
-
Include pagination for collections
-
Document with OpenAPI/Swagger