API Design

API Design

Contract-first interface design with REST conventions, resilience patterns, and Hyrum's Law awareness.

Core principle: Every behavior you expose becomes a contract. Design the smallest observable surface area you're willing to support forever.

When to Use

• Designing new API endpoints
• Designing function/class interfaces
• Adding resilience (circuit breaker, retry) to service calls
• Reviewing API design for consistency
• Writing health check endpoints

When NOT to Use

• Database schema design (use database-design skill)
• System-level architectural decisions (use system-design skill)

Contract-First Design

Define the interface before implementing it:

// Step 1: Define the contract
interface TaskRepository {
  findById(id: TaskId): Promise<Task | null>;
  save(task: Task): Promise<void>;
  delete(id: TaskId): Promise<void>;
  findByUser(userId: UserId, options?: QueryOptions): Promise<Task[]>;
}

// Step 2: Implement for production
class PostgresTaskRepository implements TaskRepository { ... }

// Step 3: Implement for tests
class InMemoryTaskRepository implements TaskRepository { ... }

Why: Forces you to think from the caller's perspective before the implementer's.

REST Conventions

URL Structure

Collections:  GET    /tasks          — list
              POST   /tasks          — create

Resources:    GET    /tasks/:id      — read
              PUT    /tasks/:id      — replace (all fields)
              PATCH  /tasks/:id      — partial update
              DELETE /tasks/:id      — delete

Nested:       GET    /users/:id/tasks — tasks owned by user

Rules:

• Plural nouns for collections (/tasks not /task)
• Never verbs in URLs (/tasks not /getTasks)
• Nested resources for ownership (/users/:id/tasks)
• Query params for filtering, sorting, pagination — never in body

HTTP Status Codes

Request/Response Shape

// List response: always paginated
GET /tasks?status=pending&limit=20&cursor=abc123
{
  "data": [...],
  "pagination": {
    "cursor": "xyz789",
    "hasMore": true,
    "total": 142
  }
}

// Error response: consistent shape
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Title is required",
    "field": "title"
  }
}

Hyrum's Law

"With a sufficient number of users of an API, all observable behaviors will be depended on by somebody."

Implications for design:

Practice: Before exposing any behavior, ask: "Am I willing to support this forever?"

Designing the Smallest Surface

• Accept the most general type, return the most specific
• Use opaque IDs (strings) not sequential integers
• Version your API from day one (/v1/tasks)
• Never remove fields — deprecate and maintain
• Document what you guarantee, not what happens to work

Interface Design Rules

Resilience Patterns

Circuit Breaker

Stops cascading failures when a dependency is down:

class CircuitBreaker {
  private failures = 0;
  private lastFailure?: Date;
  private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED';

  constructor(private threshold = 5, private timeoutMs = 30_000) {}

  async call<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === 'OPEN') {
      const elapsed = Date.now() - this.lastFailure!.getTime();
      if (elapsed < this.timeoutMs) throw new CircuitOpenError();
      this.state = 'HALF_OPEN';
    }
    try {
      const result = await fn();
      this.failures = 0;
      this.state = 'CLOSED';
      return result;
    } catch (err) {
      this.failures++;
      this.lastFailure = new Date();
      if (this.failures >= this.threshold) this.state = 'OPEN';
      throw err;
    }
  }
}

Retry with Exponential Backoff

async function withRetry<T>(
  fn: () => Promise<T>,
  { maxAttempts = 3, baseDelayMs = 100, maxDelayMs = 5000 } = {}
): Promise<T> {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (attempt === maxAttempts) throw err;
      const jitter = Math.random() * 100;
      const delay = Math.min(baseDelayMs * 2 ** (attempt - 1) + jitter, maxDelayMs);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

Retry only for: Network timeout, 429 (rate limit), 503 (unavailable). Never retry: 400, 401, 403, 404, 422 (these won't change on retry).

Health Check Endpoint

Every service must expose /health:

app.get('/health', async (req, res) => {
  const checks = await Promise.allSettled([
    db.query('SELECT 1').then(() => ({ status: 'ok' })),
    redis.ping().then(() => ({ status: 'ok' })),
  ]);

  const results = {
    database: checks[0].status === 'fulfilled' ? 'ok' : 'error',
    cache: checks[1].status === 'fulfilled' ? 'ok' : 'error',
  };

  const healthy = Object.values(results).every(v => v === 'ok');
  res.status(healthy ? 200 : 503).json({
    status: healthy ? 'ok' : 'degraded',
    checks: results,
    timestamp: new Date().toISOString(),
    version: process.env.APP_VERSION,
  });
});

Verification Checklist

REST:

• URLs use plural nouns, no verbs
• HTTP status codes match semantics
• List endpoints are paginated with cursor/limit
• Error responses have consistent shape with code, message
• Breaking changes are versioned (/v2/)

Interface design:

• Contract defined before implementation
• Parameters ≤ 4 (or options object)
• No boolean parameters
• Single responsibility per function
• Test implementation (InMemory/Fake) exists alongside production implementation

Resilience:

• Circuit breaker on all external service calls
• Retry only on transient errors (not 4xx)
• Health check endpoint at /health with dependency checks
• Timeouts set on all outbound requests

Hyrum's Law:

• No sequential integer IDs exposed externally
• Versioning strategy defined from day one
• Only behaviors you intend to maintain are documented