Backend · Interface· 7 min read
API design rules: predictable endpoints, pagination, and error contracts
Designing clean RESTful contracts. Consistent resource naming, RFC 7807 problem details, cursor-based pagination, and backward-compatible schema versioning.
API DesignRESTPaginationError Handling
On this page
A clean API is intuitive without consulting documentation. If an endpoint uses snake_case in one route and camelCase in another, or returns a 200 OK with `{ error: 'Invalid token' }`, developer experience disintegrates. Across all our platforms, we follow strict RESTful standards.
Standardized RFC 7807 error format
json
{
"type": "https://api.pratulmakar.me/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "The request payload failed schema validation constraints.",
"instance": "/api/v1/employees",
"errors": [
{ "field": "email", "message": "Must be a valid corporate email address" },
{ "field": "joinedAt", "message": "Date cannot be in the future" }
]
}