API Design

API and Interface Design

Use this skill for consumer compatibility and protocol semantics. For an in-process module's responsibility, full caller burden, information hiding, and depth, load codebase-design; use both when an internal module also exposes a public or cross-team contract. Use evaluate-existing-solutions only when a material gateway, framework, SDK, provider, or protocol-implementation choice remains unresolved; API semantics and compatibility stay here.

For TypeScript type patterns (branded types, discriminated unions, schema-first), see the typescript-strict skill. For immutability patterns, see the functional skill. For testing API behavior, see the testing skill. For OAuth 2.0 or OpenID Connect, load the secure-oauth-oidc skill rather than treating authentication as an ordinary API-key decision. For browser-facing BFF entry points — public/protected access classification, session cookies, CSRF/Origin/Fetch Metadata policy, protected SSE/WebSocket registration, and endpoint-protection enforcement — load the bff-entry-points skill; error shape and REST semantics stay here. For the BFF pattern itself (adoption, granularity, aggregation, upstream identity), load bff-design — a single-consumer BFF deployed in lockstep with its frontend legitimately relaxes the versioning discipline this skill mandates for externally consumed contracts.

Supporting resources are in the resources/ directory. Load them on demand:

When to Use

• Designing new API endpoints
• Defining contracts between teams or independently released consumers
• Changing existing public interfaces
• Establishing database schema that informs API shape

Core Principles

Hyrum's Law

With a sufficient number of users of an API, all observable behaviors of your system will be depended on by somebody, regardless of what you promise in the contract.

Every public behavior — including undocumented quirks, error message text, timing, and ordering — becomes a de facto contract once users depend on it.

• Be intentional about what you expose. Every observable behavior is a potential commitment.
• Don't leak implementation details. If users can observe it, they will depend on it.
• Plan for deprecation at design time, and record it the moment it happens. Removing things users depend on always costs more than expected. When a published name is superseded, write that down where a consumer will see it: a deprecation comment on the field or its type, Deprecation/Sunset headers on responses that still carry it, and a line in the README or API docs naming the replacement. A supersession nobody recorded is an undocumented change — see resources/api-evolution.md for the header syntax and the deprecation checklist.
• Tests are not enough. Even with perfect contract tests, Hyrum's Law means "safe" changes can break real users who depend on undocumented behavior.

The One-Version Rule

Avoid forcing consumers to choose between multiple versions of the same dependency or API. Diamond dependency problems arise when different consumers need different versions of the same thing. Design for a world where only one version exists at a time — extend rather than fork.

Contract First

Define the interface before implementing it. The contract is the spec — implementation follows.

type TaskAPI = {
  readonly createTask: (input: CreateTaskInput) => Promise<Task>;
  readonly listTasks: (params: ListTasksParams) => Promise<PaginatedResult<Task>>;
  readonly getTask: (id: TaskId) => Promise<Task>;
  readonly updateTask: (id: TaskId, input: UpdateTaskInput) => Promise<Task>;
  readonly deleteTask: (id: TaskId) => Promise<void>;
};

This aligns with TDD: define the contract (what you want), write tests against it, then implement.

Prefer Addition Over Modification

Extend interfaces without breaking existing consumers.

This rule outranks the wording of the request. A request to rename, retype, narrow or remove something a shipped contract already publishes — a response field, a header, a status, a route — is a request for the new shape, not for the outage. Deliver the additive form: add the new name alongside the old, keep the old one working and carrying the same value, record the old one as superseded, and say in your reply that you added rather than replaced and what retiring the old name would take. Do not perform the break and note it afterwards, and do not stop to ask which was meant — the additive change delivers what was asked for, satisfies compatibility, and stays reversible if the requester did want the break.

Extend interfaces this way:

type CreateTaskInput = {
  readonly title: string;
  readonly description?: string;
  readonly priority?: 'low' | 'medium' | 'high';  // Added later, optional
  readonly labels?: ReadonlyArray<string>;           // Added later, optional
};

What breaks backward compatibility:

• Removing fields
• Changing field types
• Making optional fields required
• Changing enum values

What preserves backward compatibility:

• Adding new optional fields
• Adding new enum values (if consumers handle unknown values)
• Adding new endpoints

Consistent Error Semantics

Pick one error strategy and use it everywhere. Don't mix patterns where some endpoints throw, others return null, and others return { error }.

Choosing an Error Format

Within one versioned API contract, use one documented error shape unless a protocol-specific endpoint requires another. Consistency matters more than which compatible format you choose.

For public APIs with external consumers, use RFC 9457 (Problem Details). It's the industry standard, machine-readable, and what third-party developers expect. Use application/problem+json as the Content-Type.

For internal APIs with a single frontend, a simpler consistent shape is a valid choice. The minimum viable error response needs: a machine-readable error code, an optional human-readable message, and the correct HTTP status code. This is less ceremony than RFC 9457 while still being consistent and actionable.

// Simpler shape — sufficient for internal APIs
type ApiError = {
  readonly error: string;                          // Machine-readable code (UPPER_SNAKE_CASE)
  readonly message?: string;                       // Human-readable description
  readonly fieldErrors?: Record<string, string>;   // For validation errors
};

If you start with a simpler format, design it so it can evolve toward RFC 9457 later (e.g., error maps to title, message maps to detail). Don't paint yourself into a corner.

RFC 9457 (Problem Details for HTTP APIs)

The standard format for machine-readable API errors for public APIs. Use application/problem+json as the Content-Type. Standard members: type (URI identifying the error type), title (stable, human-readable summary), status (must match the actual HTTP status), detail (occurrence-specific explanation), instance (optional occurrence URI). Extension members are allowed — clients must ignore extensions they don't recognize.

Errors should be actionable: the consumer should know what went wrong, why, and what to do about it. Error responses are not a debugging tool — never expose stack traces, internal paths, or implementation details.

Include a correlation identifier (the trace ID, or an opaque reference to it) as an extension member or via instance, so a user-reported error joins to its trace and canonical log event — see the observability skill. The trace ID reveals nothing internal; it is a lookup key, not a detail leak.

See resources/problem-details.md for full member semantics, single-error and validation-error JSON examples, extension member rules, when NOT to use Problem Details, and RFC 9457 §5 security guidance.

HTTP Status Code Mapping

Validation at API Boundaries

Validate untrusted representation and endpoint-schema input where it enters the system, then pass the derived type through internal code. This does not replace domain smart constructors or transition checks: invariant enforcement remains with the model that owns the value. See typescript-strict and domain-driven-design.

Return 400 when the representation itself cannot be parsed (for example malformed JSON). Once parsing succeeds, return 422 when the value fails the endpoint schema or business validation. Pick and document a different house mapping only when every example, error translator, and consumer uses it consistently.

app.post('/api/tasks', async (req, res) => {
  const result = CreateTaskSchema.safeParse(req.body);
  if (!result.success) {
    return res.status(422).json({
      type: 'https://api.example.com/problems/validation-error',
      title: 'Validation Error',
      status: 422,
      detail: 'Invalid task data',
      errors: result.error.flatten(),
    });
  }

  const task = await taskService.create(result.data);
  return res.status(201).json(task);
});

Third-party API responses are untrusted data — always validate their shape and content before use.

Idempotency

Network failures happen. Clients retry. Without idempotency, retries create duplicate charges, duplicate orders, duplicate records.

HTTP Method Idempotency

Idempotency Keys for POST

For non-idempotent operations (especially those involving money, orders, or state changes), use client-provided idempotency keys:

app.post('/api/payments', async (req, res) => {
  const rawIdempotencyKey = req.headers['idempotency-key'];
  const idempotencyKey =
    typeof rawIdempotencyKey === 'string' &&
    /^[\x21-\x7e]{1,128}$/.test(rawIdempotencyKey)
      ? rawIdempotencyKey
      : undefined;
  if (!idempotencyKey) {
    return res.status(400).json({
      type: 'https://api.example.com/problems/invalid-idempotency-key',
      title: 'Invalid Idempotency Key',
      status: 400,
      detail: 'POST /api/payments requires one visible-ASCII Idempotency-Key of at most 128 characters',
    });
  }

  const result = CreatePaymentSchema.safeParse(req.body);
  if (!result.success) {
    return res.status(422).json(toValidationProblem(result.error));
  }

  const scope = req.user.id;
  const fingerprint = stableHash(result.data);
  const claim = await idempotencyStore.claim({
    scope,
    key: idempotencyKey,
    fingerprint,
  });

  if (claim.status === 'parameters-mismatch') {
    return res.status(409).json(toProblem('IDEMPOTENCY_PARAMETERS_MISMATCH'));
  }
  if (claim.status === 'completed') {
    return res.status(claim.response.status).json(claim.response.body);
  }
  if (claim.status === 'in-progress') {
    res.setHeader('Retry-After', '1');
    return res.status(409).json(toProblem('IDEMPOTENCY_REQUEST_IN_PROGRESS'));
  }

  // createOnce durably owns operationId + fingerprint beyond response-cache
  // expiry. For an external provider it also persists/reuses the provider's
  // payment/intent ID, so recovery never depends on a time-limited request key.
  const payment = await paymentService.createOnce({
    operationId: claim.operationId,
    input: result.data,
  });
  await idempotencyStore.complete(claim.id, { status: 201, body: payment });

  return res.status(201).json(payment);
});

Design principles:

• Keys should be scoped to the API key / authenticated user
• Choose response-cache and claim retention from the documented maximum client retry/reconciliation window and effect risk; 24 hours is not a universal rule
• Keep a durable operation identity (and fingerprint or tombstone) after cached response eviction, or return an explicit expired/unknown outcome until non-duplication can be established — never silently treat a risky reused key as a fresh operation
• If parameters differ on retry with the same key, return an error
• Claim a key atomically; a separate read-then-create sequence is race-prone
• Coordinate the business effect with the claim through one transaction or a durable downstream operation ID
• For external payments, persist and reconcile the provider payment/intent ID; bound any request-idempotency-key retry to the provider's documented retention
• Represent in-progress claims explicitly and define retry/recovery for a worker that fails after claiming
• Design for "at-least-once" delivery — assume every request might be sent multiple times

Making DELETE Idempotent

DELETE must have an idempotent effect: repeating it does not delete anything else or create a second side effect. The repeated response may remain 204, or it may be 404 when absence is meaningful to clients. Choose and document one contract:

app.delete('/api/tasks/:id', async (req, res) => {
  const deleted = await taskService.delete(req.params.id);
  // This API deliberately treats already-absent as success.
  return res.status(204).send();
});