Durable APIs: pagination, idempotency, versioning, and rate limits

An API is a long-term contract#

APIs connect systems. Good APIs are predictable, debuggable, safe to retry, and able to evolve without breaking clients unexpectedly.

Pagination#

Listing endpoints should not return everything. Offset pagination is simple but can be slow or unstable for large changing data sets. Cursor pagination is often better for feeds and large lists.

GET /api/posts?limit=20&cursor=2026-04-25T08:00:00Z

Idempotency#

Retrying the same sensitive mutation should not create duplicate side effects. Payment, order creation, email sending, and webhook processing often need idempotency keys.

POST /api/orders
Idempotency-Key: 7a2f4e7f-7c2f-4e2f-8c2d-72d2a6c9a111

Versioning and errors#

Adding fields is usually safe; removing fields, changing types, or changing status code meanings can break clients. Use versioning and deprecation windows for significant changes.

{
  "error": {
    "code": "validation_failed",
    "message": "Title is required.",
    "fields": {
      "title": "Required"
    }
  }
}

Rate limits#

Login, search, contact, comments, uploads, and AI generation endpoints need abuse protection. Return 429 when appropriate and include retry guidance when useful.

Primary references#

• MDN: HTTP response status codes
• OWASP API Security Top 10 2023
• MDN: Retry-After header