api-design

API Design Principles

RESTful Conventions

Resource Naming

• Use plural nouns for collections: /users, /orders
• Use lowercase with hyphens for readability: /user-profiles
• Nest resources to show relationships: /users/{userId}/orders
• Keep URLs short and intuitive
• Avoid verbs in URLs (use HTTP methods instead)

Examples

GET    /users              # Get all users
GET    /users/{id}         # Get specific user
POST   /users              # Create user
PUT    /users/{id}         # Update user (full replacement)
PATCH  /users/{id}         # Partial update
DELETE /users/{id}         # Delete user

HTTP Methods & Status Codes

Operation	Method	Success	Error Cases
Get single item	GET	200 OK	404 Not Found
Get collection	GET	200 OK (empty array if none)	—
Create	POST	201 Created	400 Bad Request, 409 Conflict
Full update	PUT	200 OK or 204 No Content	404 Not Found, 400 Bad Request
Partial update	PATCH	200 OK	404 Not Found, 400 Bad Request
Delete	DELETE	204 No Content	404 Not Found

Status Code Guidelines

2xx Success

• 200 OK - Request succeeded, response has body
• 201 Created - Resource created, include Location header
• 204 No Content - Request succeeded, no response body

3xx Redirection

• 301 Moved Permanently - Resource permanently moved
• 302 Found - Temporary redirect
• 304 Not Modified - Resource not modified (caching)

4xx Client Errors

• 400 Bad Request - Invalid syntax or validation failure
• 401 Unauthorized - Authentication required or failed
• 403 Forbidden - Authenticated but not authorized
• 404 Not Found - Resource doesn't exist
• 409 Conflict - Request conflicts with current state (duplicate)
• 422 Unprocessable Entity - Validation errors
• 429 Too Many Requests - Rate limit exceeded

5xx Server Errors

• 500 Internal Server Error - Unexpected server error
• 502 Bad Gateway - Invalid response from upstream
• 503 Service Unavailable - Temporarily unavailable
• 504 Gateway Timeout - Upstream timeout