REST API Design Best Practices: Build APIs Developers Love

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/getUserPosts

HTTP 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 exceeded

Consistent 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,excerpt

Follow these patterns consistently, document with OpenAPI/Swagger, and your API consumers will thank you.