Build well-designed, consistent, and developer-friendly APIs using industry best practices and proven design patterns.
URLs should represent resources (nouns), not actions (verbs). Use HTTP methods to define operations.
/users/products/123/getUsers/deleteProduct/123Each request should contain all information needed. Server shouldn't store client state between requests.
Use standard HTTP methods, status codes, and conventions consistently across all endpoints.
Represent relationships through nested resources and clear hierarchies.
/users/123/posts/posts/456/comments/orders/789/itemsRetrieve data without side effects. Should be safe and idempotent.
Create new resources. Not idempotent - multiple identical requests create multiple resources.
Replace entire resource. Idempotent - same request produces same result.
Partially update resource. Only include fields to change. Idempotent.
Delete resources. Idempotent - deleting same resource multiple times has same effect.
An idempotent operation produces the same result when called multiple times with identical parameters. This is crucial for reliable APIs.
GET- Always safe and idempotentPUT- Replace resource with same dataPATCH- Update same fields to same valuesDELETE- Deleting deleted resource returns 404POST- Creates new resource each timeUse idempotency keys to prevent duplicate resource creation:
For operations that don't fit CRUD, use action verbs as sub-resources:
200 OK - Successful GET, PUT, PATCH, DELETE201 Created - Successful POST (resource created)204 No Content - Successful DELETE (no response body)400 Bad Request - Invalid request data401 Unauthorized - Missing or invalid authentication403 Forbidden - Insufficient permissions404 Not Found - Resource doesn't exist409 Conflict - Resource already exists422 Unprocessable Entity - Validation failed429 Too Many Requests - Rate limit exceeded500 Internal Server Error - Unexpected error503 Service Unavailable - Temporary downtime