API and Interface Design

---
name: api-and-interface-design
description: Use when designing APIs, module boundaries, or any public interface before implementation. Triggers on "design this endpoint", "API contract", "interface between", REST or GraphQL endpoint creation, type contracts between modules, or changes to an existing public interface.
---

# API and Interface Design

An interface is a promise, and Hyrum's Law sets the terms: with a sufficient number of consumers, every observable behavior of your system will be depended on by somebody, regardless of what the contract says. Design is therefore the act of deciding, deliberately, what to expose. Everything exposed by accident is still a commitment.

## The five commitments

### 1. Contract first
Write the interface before the implementation. The contract is the specification: typed request and response schemas, error shapes, and naming, committed before handler code exists. Types are documentation; "we will document it later" means the implementation becomes the contract by default.

### 2. One error strategy
Pick one error format and apply it to every endpoint. A structured body with a machine-readable code and a human-readable message, plus a consistent status-code mapping: 400 malformed input, 401 unauthenticated, 403 unauthorized, 404 missing, 409 conflict, 422 validation failure, 500 server fault. An API where each endpoint fails differently forces every consumer to write per-endpoint error handling.

### 3. Validate at boundaries
Validate where external input enters the system — API handlers, form submissions, environment variables, and every third-party API response, which is untrusted data no matter how reputable the vendor. Inside the boundary, trust your own code. Validation scattered through internal layers is noise that hides the one place validation actually matters.

### 4. Additive evolution
Extend interfaces with new optional fields. Do not change the type of an existing field, and do not remove a field consumers have seen. When behavior must genuinely change, add the new shape alongside the old and plan the deprecation — deprecation is a design-time concern, not an afterthought. Related: avoid forcing consumers to choose between multiple live versions of the same contract; one version at a time, extended rather than forked.

### 5. Predictable naming
- REST resources: plural nouns, no verbs in URLs
- Query parameters and response fields: camelCase
- Booleans: is/has/can prefixes
- Enum values: UPPER_SNAKE

## REST patterns

```
GET    /api/tasks            list (paginated, filterable)
POST   /api/tasks            create
GET    /api/tasks/:id        retrieve
PATCH  /api/tasks/:id        partial update — only provided fields change
DELETE /api/tasks/:id        delete
GET    /api/tasks/:id/comments   sub-resource
```

List endpoints paginate from version one (page, pageSize, totalItems, totalPages in the response). Retrofitting pagination onto an unpaginated endpoint is a breaking change; shipping it on day one is a few lines. Filters go in query parameters: `?status=in_progress&assignee=user123`.

## TypeScript contract patterns

- **Discriminated unions** for variants — a `status` or `type` discriminator gives consumers type narrowing instead of optional-field guessing.
- **Input/output separation** — the type a caller submits is not the type the server returns; server-generated fields (id, createdAt) belong only in the output type.
- **Branded ID types** — brand ID strings so an orderId cannot be passed where a paymentId belongs; the compiler catches the swap.

## Red flags

- An endpoint that returns different shapes depending on internal conditions
- Error formats that differ between endpoints
- Validation logic scattered through internal layers
- A changed field type or a removed field on a shipped interface
- A list endpoint without pagination
- Verbs in REST URLs
- A third-party API response used without validation

## Verification checklist

- [ ] Every endpoint has typed input and output schemas, committed with (or before) the implementation
- [ ] Error responses follow one format, everywhere
- [ ] Validation happens at boundaries; internal layers trust their inputs
- [ ] List endpoints paginate
- [ ] Every change to a shipped interface is additive and optional
- [ ] Naming follows the conventions above without exceptions

## Scope

This skill shapes contracts before implementation. Documenting a shipped interface is api-documentation-writer's job; recording why a design was chosen is adr-writer's; reviewing module depth in existing code is codebase-architecture-reviewer's. Use this one while the interface is still cheap to change.