API Design Principles That Stand the Test of Time — and the Ones That Don't

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json

{
  "type": "https://api.rrezvin.com/errors/rate-limited",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded the rate limit of 100 requests per minute. Retry after 42 seconds.",
  "instance": "/orders/req-def456"
}

HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json

{
  "type": "https://api.rrezvin.com/errors/dependency-down",
  "title": "Payment Service Unavailable",
  "status": 503,
  "detail": "The payment processing service is temporarily unavailable. Our team has been notified.",
  "instance": "/orders/req-ghi789",
  "retryAfter": 30
}
``$

**The `type` field is the key.** It's a stable identifier that clients can switch on. Don't make it `about:blank` — make it a documented URI that links to documentation for that error class.

// Client-side handling — switching on the type URI

async function createOrder(input: CreateOrderInput): Promise<Order> {

const response = await fetch("/orders", { method: "POST", body: JSON.stringify(input) });

if (!response.ok) {

const problem = await response.json() as ProblemDetails;

switch (problem.type) {

case "https://api.rrezvin.com/errors/validation-error":

// Show field-level errors in the form

for (const err of problem.errors ?? []) {

showFieldError(err.field, err.message);

}

return;

case "https://api.rrezvin.com/errors/rate-limited":

// Extract retry info from headers

const retryAfter = response.headers.get("Retry-After");

scheduleRetry(Number(retryAfter) * 1000);

return;

case "https://api.rrezvin.com/errors/dependency-down":

showBanner("Payment is temporarily unavailable. Please try again later.");

return;

default:

showBanner("Something went wrong. Our team has been notified.");

reportError(problem);

return;

}

}

return response.json();

}

Versioning: The Anti-Pattern Hall of Fame

The Better Way: Compatible Evolution

The vast majority of API changes can be backward-compatible:

// Adding a field — always compatible
interface OrderV1 {
  id: string;
  status: string;
  total: number;
}

// ✅ V2: New optional field, old clients ignore it
interface OrderV2 {
  id: string;
  status: string;
  total: number;
  discountApplied?: number;  // optional = non-breaking
}

// Adding an enum value — compatible 99% of the time
type OrderStatus = "pending" | "confirmed" | "shipped" | "delivered" | "cancelled" | "refunded";

// Changing a field type — NOT compatible
interface OrderV3 {
  // ❌ Changed from number to string — breaks every client
  total: string;
}
``$

**Rules for compatible evolution:**
1. Never remove a field — mark it deprecated and document the replacement
2. Never change a field's type — add a new field instead
3. Never require a new field — all new fields are optional
4. Never change the semantics of an existing field — create a new endpoint if behaviour differs

### When You Actually Need Versioning

There are two scenarios where versioning is justified:

1. **Security-critical changes** — You discover a fundamental design flaw that creates a vulnerability
2. **Fundamental semantics changed** — Your `status` field had three values and now it has ten, and clients built switch statements on the original three

In those cases, use **header-based versioning**, not URL-based:

// ❌ URL versioning — pollutes URIs, makes tooling harder

GET /v2/users/123

// ✅ Accept header versioning — clean URIs, explicit opt-in

GET /users/123

Accept: application/json; version=2

// ✅ Custom header — also valid, same principle

GET /users/123

X-API-Version: 2

The reason: URL versioning encourages running multiple API versions in the same codebase, which becomes a maintenance nightmare. Header-based versioning makes you think about the migration, and the version is metadata about the request, not the resource.

Sunset Headers: Do Your Clients a Favour

When you deprecate a field or endpoint, tell clients about it in-band:

// Response headers for deprecated fields
HTTP/1.1 200 OK
Sunset: Sat, 31 Dec 2026 23:59:59 GMT
Deprecation: true
Link: <https://api.rrezvin.com/docs/migration-v2>; rel="deprecation"

{
  "id": "123",
  "status": "confirmed",
  "total": 29900,
  "discountApplied": 5000,
  // Deprecated field — still present, but clients should migrate
  "coupon_code_deprecated": "SUMMER2025"
}
`

// Middleware to set deprecation headers
function deprecateEndpoint(deprecatedAt: Date, sunsetAt: Date) {
  return (req: Request, res: Response, next: NextFunction) => {
    res.setHeader("Deprecation", "true");
    res.setHeader("Sunset", sunsetAt.toUTCString());
    res.setHeader("Link", '<https://api.rrezvin.com/docs/migration>; rel="deprecation"');
    next();
  };
}
``$

Give clients at least six months between deprecation and removal. A year is better.

## Pagination: The Decision That Ages

Every API starts with no pagination, adds it at 10,000 records, and regrets the choice at 100,000. The pagination pattern you choose affects client code, database load, and frontend UX for the life of the API.

### Offset Pagination (The Default — But Wrong Choice)

// The temptation — simple to implement, terrible at scale

GET /orders?offset=100&limit=50

Cursor-Based Pagination (The Right Choice)

// Cursor-based — stable, fast, consistent
GET /orders?cursor=eyJpZCI6IjEyMyJ9&limit=50

// The response
{
  "data": [...],
  "nextCursor": "eyJpZCI6IjUwMCJ9",
  "hasMore": true
}
``
``

// Server-side implementation

async function paginateOrders(

db: Pool,

cursor?: string,

limit: number = 50

): Promise<PaginatedResponse<Order>> {

const decoded = cursor ? decodeCursor(cursor) : null;

const query = decoded

const params = decoded

? [decoded.createdAt, decoded.id, limit + 1]

: [limit + 1];

const result = await db.query(query, params);

const rows = result.rows.slice(0, limit);

const hasMore = result.rows.length > limit;

return {

data: rows,

nextCursor: hasMore

? encodeCursor({ id: rows[rows.length - 1].id, createdAt: rows[rows.length - 1].created_at })

: null,

hasMore,

};

}

// Cursor encoding — opaque to clients, includes only what we need

function encodeCursor(params: { id: string; createdAt: string }): string {

return Buffer.from(JSON.stringify(params)).toString("base64url");

}

function decodeCursor(cursor: string): { id: string; createdAt: string } {

return JSON.parse(Buffer.from(cursor, "base64url").toString());

}

Consistent Field Ordering

Paired with cursor pagination, you need stable sorting:

// Always order by (created_at DESC, id DESC) — not just created_at
// Why: created_at can have ties (same millisecond). id breaks the tie.
const query = `
  SELECT * FROM orders
  WHERE (created_at, id) < ($1::TIMESTAMPTZ, $2::UUID)
  ORDER BY created_at DESC, id DESC
  LIMIT $3

Idempotency: The Killer Feature Your API Needs

An idempotent API lets clients safely retry requests. Without it, every network error becomes a potential duplicate charge, duplicate order, or duplicate email.

The Idempotency Key Pattern

interface CreateOrderRequest {
  items: OrderItem[];
  idempotencyKey: string; // Client-generated UUID
}

async function handleCreateOrder(req: Request, res: Response): Promise<void> {
  const { idempotencyKey, items } = req.body;

  await db.transaction(async (tx) => {
    // Check if we've already processed this key
    const existing = await tx.query(
      "SELECT response_body FROM idempotency_cache WHERE key = $1",
      [idempotencyKey]
    );

    if (existing.rows.length > 0) {
      // Return the cached response — no side effects
      res.status(201).json(existing.rows[0].response_body);
      return;
    }

    // Process the request — guaranteed only once per key
    const order = await createOrder(tx, items);

    // Cache the response with a TTL
    await tx.query(
      `INSERT INTO idempotency_cache (key, response_body, created_at)
       VALUES ($1, $2, NOW())`,
      [idempotencyKey, JSON.stringify(order)]
    );

    res.status(201).json(order);
  });
}

Rate Limiting: Tell Clients What to Do

1. How many requests they can make
2. When the window resets
3. How long to wait

// Rate limit middleware with informative headers

function rateLimiter(opts: { maxRequests: number; windowMs: number }) {

const store = new SlidingWindowStore(opts);

return (req: Request, res: Response, next: NextFunction) => {

const result = store.check(req.ip);

// Informational headers — present on every response

res.setHeader("X-RateLimit-Limit", opts.maxRequests);

res.setHeader("X-RateLimit-Remaining", result.remaining);

if (result.shouldLimit) {

const resetTime = new Date(Date.now() + opts.windowMs);

res.setHeader("Retry-After", Math.ceil(opts.windowMs / 1000));

res.setHeader("X-RateLimit-Reset", resetTime.toISOString());

res.status(429).json({

type: "https://api.rrezvin.com/errors/rate-limited",

title: "Rate Limit Exceeded",

status: 429,

});

return;

}

next();

};

}

The Consistency Checklist

Before shipping any endpoint, run this checklist:

Final Thought

The API you design today will be consumed by clients you haven't imagined, from devices that don't exist yet, operated by developers who will judge your competence based on your error messages and pagination decisions.