API
Backend
Best Practices
Node.js
Software Engineering
Blog AI Assistant
Ask anything about this article
Hi! I've read this article.
What would you like to know?
Ask anything about this article
Hi! I've read this article.
What would you like to know?
@farhan
A well-designed API is like a well-designed user interface — intuitive, consistent, and hard to misuse. After building and consuming hundreds of APIs, here are the practices that separate good APIs from great ones.
The HTTP method already contains the verb. Your URL should describe the resource.
❌ GET /getUsers
❌ POST /createUser
❌ PUT /updateUser/123
✅ GET /users → List users
✅ POST /users → Create user
✅ GET /users/123 → Get specific user
✅ PUT /users/123 → Update user
✅ DELETE /users/123 → Delete user
200 OK → Successful GET/PUT
201 Created → Successful POST
204 No Content → Successful DELETE
400 Bad Request → Client sent invalid data
401 Unauthorized → Missing/invalid authentication
403 Forbidden → Authenticated but not authorized
404 Not Found → Resource doesn't exist
409 Conflict → Resource conflict (duplicate)
422 Unprocessable → Validation errors
429 Too Many → Rate limit exceeded
500 Server Error → Something broke on our end
Never return plain strings. Use a structured error format:
json{
"error": {
"code": "VALIDATION_ERROR",
"message": "The request body contains invalid fields",
"details": [
{
"field": "email",
"message": "Must be a valid email address"
},
{
"field": "age",
"message": "Must be a positive integer"
}
]
}
}
Never return unbounded lists. Always paginate:
GET /users?page=2&limit=20
Response:
{
"data": [...],
"pagination": {
"page": 2,
"limit": 20,
"total": 150,
"totalPages": 8,
"hasNext": true,
"hasPrev": true
}
}
For large datasets, use cursor-based pagination:
GET /users?cursor=eyJpZCI6MTIzfQ&limit=20
Always version your API from day one:
✅ /api/v1/users
✅ /api/v2/users
GET /users?role=admin&status=active → Filtering
GET /users?sort=created_at&order=desc → Sorting
GET /users?search=john → Searching
GET /users?fields=id,name,email → Field selection
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1640000000
Use Bearer tokens in the Authorization header:
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Never put tokens in query parameters — they end up in server logs and browser history.
These practices aren't opinions — they're the result of decades of collective experience building APIs at scale. Follow them, and your API consumers will thank you.
