A well-designed API is the difference between developers adopting your service enthusiastically or abandoning it. Companies like Stripe and Twilio are famous for their API design quality.
Resource Naming
✓ Good ✗ Bad
GET /api/users GET /api/getUsers
GET /api/users/42 GET /api/user?id=42
POST /api/users POST /api/createUser
PUT /api/users/42 POST /api/updateUser
DELETE /api/users/42 POST /api/deleteUser
GET /api/users/42/posts GET /api/getUserPostsHTTP Status Codes
200 OK — Successful GET/PUT
201 Created — Successful POST
204 No Content — Successful DELETE
400 Bad Request — Validation errors
401 Unauthorized — Missing authentication
403 Forbidden — Not allowed
404 Not Found — Resource doesn't exist
422 Unprocessable — Semantic validation errors
429 Too Many — Rate limit exceededConsistent Error Response
{
"error": {
"code": "VALIDATION_ERROR",
"message": "The given data was invalid.",
"details": [
{"field": "email", "message": "The email has already been taken."},
{"field": "password", "message": "Must be at least 8 characters."}
]
}
}Cursor-Based Pagination
GET /api/posts?cursor=eyJpZCI6MTB9&per_page=20
Response:
{
"data": [...],
"meta": {
"per_page": 20,
"next_cursor": "eyJpZCI6MzB9",
"prev_cursor": "eyJpZCI6MTF9"
}
}Filtering, Sorting, and Field Selection
GET /api/posts?filter[status]=published&filter[category]=laravel
GET /api/posts?sort=-created_at,title
GET /api/posts?fields=id,title,excerptFollow these patterns consistently, document with OpenAPI/Swagger, and your API consumers will thank you.