Designing RESTful APIs That Developers Love
By Stanley Hayford ·
API Design Principles
A well-designed API is intuitive, consistent, and hard to misuse. Here are the principles I follow after years of building production APIs.
Resource Naming
- Use nouns, not verbs:
/usersnot/getUsers - Use plural forms:
/projectsnot/project - Use kebab-case:
/blog-postsnot/blogPosts - Nest logically:
/courses/:id/lessons
HTTP Methods
| Method | Purpose | Idempotent |
|---|---|---|
| GET | Read | Yes |
| POST | Create | No |
| PUT | Full update | Yes |
| PATCH | Partial update | Yes |
| DELETE | Remove | Yes |
Error Responses
Always return consistent error objects:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Email is required",
"field": "email"
}
}
Pagination
Use cursor-based pagination for large datasets, offset-based for smaller ones:
GET /api/posts?page=2&limit=20&sort=createdAt&order=desc
Versioning
Use URL path versioning for simplicity: /api/v1/users. Header-based versioning is cleaner but harder to test.
Rate Limiting
Always implement rate limiting. Return 429 Too Many Requests with Retry-After header.
Documentation
Use OpenAPI/Swagger. Auto-generate docs from your code. Keep examples up to date.
Tags: API Design, REST, Backend, Best Practices