rest-api-design

# 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 ```json { "data": { "id": "123", "type": "user", "attributes": { "name": "John", "email": "john@example.com" } }, "meta": { "requestId": "req_abc123" } } ``` ## Collection Response ```json { "data": [...], "pagination": { "page": 1, "limit": 20, "total": 150, "totalPages": 8 }, "links": { "self": "/api/users?page=1", "next": "/api/users?page=2" } } ``` ## ...