Designing Clean REST & RPC APIs: Predictability, Error Handling, and Pagination

Whether you are building internal APIs for your frontend team or exposing public developer endpoints for third-party integrations, your API design directly dictates developer experience and system maintainability. An inconsistent API where one endpoint returns snake_case, another returns camelCase, and errors return HTTP 200 with an error string forces developers to write defensive glue code.

Great API design is not about dogmatic adherence to theoretical REST purity; it is about predictability, descriptive error payloads, explicit versioning, and robust pagination standards.

Core principles of predictable resource design

Follow standardized HTTP verb mappings and intuitive noun-based path hierarchies:

Resource Nouns

Use plural nouns (`/v1/customers`, `/v1/invoices`). Never put actions in paths (avoid `/v1/getCustomers`).

Standard HTTP Verbs

`GET` for read, `POST` for create, `PATCH` for partial update, `PUT` for complete replacement, `DELETE` for removal.

Consistent Casing

Standardize JSON property casing across all endpoints (camelCase or snake_case throughout; never mix).

Idempotency Keys

Accept `Idempotency-Key` headers on mutating POST endpoints (like `/v1/charges`) to prevent duplicate transactions on network retries.

Cursor-based vs Offset-based pagination

Offset-based pagination (`LIMIT 20 OFFSET 100`) is simple to write but breaks at scale: as offsets increase, database query latency degrades linearly, and users experience duplicate or skipped items when new rows are inserted during pagination.

For production data feeds, implement cursor-based pagination using an encoded pointer (such as an encrypted timestamp or base64 ID). It guarantees $O(1)$ query execution using existing indexes and provides consistent results during high-frequency writes.

An error response that returns HTTP 200 with `{ "success": false }` is a design flaw. Use standard HTTP status codes and actionable error bodies.

The anatomy of an actionable error response

• Return standard RFC 7807 problem details containing an explicit machine-readable error code (e.g., `rate_limit_exceeded`, `invalid_card`).
• Provide a human-readable explanation describing why the error occurred.
• Include a `doc_url` link pointing directly to documentation explaining how to resolve the issue.
• List specific validation errors mapped to the corresponding input field names for fast frontend form binding.