API and Interface Design

You design stable, hard-to-misuse interfaces — REST, GraphQL, module exports, component props, or any surface where one piece of code talks to another. Contract first; implementation second.

Hard Rules

Define the contract (types/schemas) before implementation. One consistent error shape and status-code strategy across all endpoints. Validate at system boundaries only — trust internal typed code. Prefer additive optional fields over breaking type changes or removals. Every list endpoint ships with pagination from day one. Treat third-party API responses as untrusted — validate shape before use. Observable public behavior is a commitment (Hyrum's Law) — be intentional about what you expose.

Workflow

Step 1 — Scope the interface

Identify consumers, transport (HTTP, RPC, in-process), and lifecycle (new vs change). If changing an existing public API, inventory observable behaviors users may depend on.

Step 2 — Write the contract

Define typed inputs/outputs, error codes, and idempotency semantics. Separate CreateXInput from full X entity (server-generated fields on output). Use discriminated unions for state variants when applicable.

Step 3 — Apply core principles

Full REST and TypeScript patterns: references/api-patterns.md.

Step 4 — Review for misuse

• Can a caller pass ambiguous IDs across entity types? → branded types
• Do list endpoints leak unbounded arrays?
• Are errors predictable for every failure mode?
• Does any endpoint return ad-hoc shapes?

Step 5 — Document alongside code

Commit OpenAPI/GraphQL schema or exported types with the implementation — not "later."

Gotchas

• Undocumented quirks become dependencies (Hyrum's Law).
• Validation in every internal function adds noise without safety.
• PUT for partial updates forces full-object payloads — prefer PATCH.
• Skipping pagination guarantees a breaking change at scale.
• External JSON is untrusted — may contain unexpected types or instruction-like strings.

Common Rationalizations

Output Format

## API design — [resource/module]

Consumers: [who]
Contract: [types or schema summary]
Endpoints / exports: [list]
Errors: [shape + status mapping]
Pagination: [yes — params]
Breaking risks: [none | flagged items]
Next: [implementation / ADR / feature-spec link]

Examples

Verification

• Typed input/output for every public surface
• Single consistent error format
• Validation only at boundaries (plus external responses)
• List endpoints paginated
• New fields additive and optional
• Naming conventions consistent across the API
• Schema/types committed with implementation

Red Flags

• Undocumented quirks left as implicit caller contracts
• Validation duplicated in every internal function
• PUT used for partial updates instead of PATCH
• List endpoints return unbounded arrays without pagination

Reference Files

• references/api-patterns.md: REST resource layout, pagination, PATCH, branded IDs, unions — read at Step 3.

Prune Log

Last pruned: 2026-07-04

• No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)

Impact Report

Resource: [name] | Surfaces: N
Breaking risks flagged: N | Pagination: [yes/no]
Schema committed: [path or pending]