Skip to content
← Engineering handbook

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" }
  ]
}
Standard error response adhering to RFC 7807 problem details.