REST API Design Principles

Well-designed APIs are intuitive and developer-friendly. Follow these principles.

Resource Naming

Use nouns, not verbs:

# Good
GET /users
GET /users/123
POST /users
PUT /users/123
DELETE /users/123

# Bad
GET /getUsers
POST /createUser
DELETE /deleteUser/123

Use Proper HTTP Methods

| Method | Purpose | Idempotent | |--------|---------|------------| | GET | Read | Yes | | POST | Create | No | | PUT | Replace | Yes | | PATCH | Partial update | Yes | | DELETE | Remove | Yes |

HTTP Status Codes

Use them correctly:

200 OK - Success
201 Created - Resource created
204 No Content - Success, no body
400 Bad Request - Client error
401 Unauthorized - Auth required
403 Forbidden - Not allowed
404 Not Found - Resource doesn't exist
422 Unprocessable Entity - Validation failed
500 Internal Server Error - Server error

Request/Response Format

Consistent JSON structure:

// Success response
{
 "data": {
 "id": 123,
 "name": "John Doe",
 "email": "john@example.com"
 }
}

// Error response
{
 "error": {
 "code": "VALIDATION_ERROR",
 "message": "Email is required",
 "details": [
 { "field": "email", "message": "This field is required" }
 ]
 }
}

Pagination

Handle large datasets:

GET /users?page=2&limit=20

Response:
{
 "data": [...],
 "pagination": {
 "page": 2,
 "limit": 20,
 "total": 150,
 "totalPages": 8
 }
}

Filtering and Sorting

Keep it intuitive:

GET /users?status=active&role=admin
GET /users?sort=createdAt&order=desc
GET /products?price_min=10&price_max=100

Versioning

Plan for changes:

# URL versioning (recommended)
GET /v1/users
GET /v2/users

# Header versioning
GET /users
Accept: application/vnd.api+json; version=2

Rate Limiting

Include headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

Conclusion

Good API design makes integration easy. Follow these principles for APIs developers will love.