Design stable, well-documented APIs and interfaces

This skill is a methodology for designing stable, well-documented interfaces that are hard to misuse - REST APIs, GraphQL schemas, module boundaries, component props, and any surface where one piece of code talks to another. It centers on Hyrum's Law: with enough users, every observable behavior of a system becomes a de facto contract, so it pushes being intentional about what is exposed, not leaking implementation details, and planning for deprecation at design time. It also applies the One-Version Rule (extend rather than fork, to avoid diamond dependency problems), contract-first design (define the interface in TypeScript before implementing it), a single consistent error shape mapped to standard HTTP status codes, validation only at system boundaries while internal code trusts its types, preferring additive optional fields over breaking changes, and predictable naming conventions - plural-noun REST endpoints, camelCase params and fields, is/has/can-prefixed booleans, and UPPER_SNAKE enum values.

Use it when designing new API endpoints, defining module boundaries or contracts between teams, creating component prop interfaces, establishing a database schema that will inform API shape, or changing an existing public interface. Its verification checklist doubles as a set of red flags for when a design is NOT ready to ship: endpoints that return different shapes depending on conditions, inconsistent error formats across endpoints, validation scattered through internal code instead of concentrated at boundaries, breaking changes to existing fields, list endpoints without pagination, verbs in REST URLs, and third-party API responses used without validation.

GET    /api/tasks              → List tasks (with query params for filtering)
POST   /api/tasks              → Create a task
GET    /api/tasks/:id          → Get a single task
PATCH  /api/tasks/:id          → Update a task (partial)
DELETE /api/tasks/:id          → Delete a task

GET    /api/tasks/:id/comments → List comments for a task (sub-resource)
POST   /api/tasks/:id/comments → Add a comment to a task

Input/output separation is explicit: a CreateTaskInput interface carries only what a caller provides, while the returned Task interface adds server-generated fields such as id, createdAt, updatedAt, and createdBy. List endpoints return a data array plus a pagination object (page, pageSize, totalItems, totalPages), and PATCH endpoints accept partial objects where only the fields provided actually change.

Patterns are worked through in TypeScript and REST: discriminated unions for status variants, so each variant carries only the fields relevant to it and consumers get type narrowing; branded types for IDs, so a UserId cannot accidentally be passed where a TaskId is expected; and a structured APIError shape mapped to standard HTTP status codes - 400 for invalid client data, 401 for missing authentication, 403 for unauthorized access, 404 for not found, 409 for conflicts, 422 for validation failures, and 500 for server errors without exposing internal details. Third-party API responses are treated as untrusted data and validated before use in any logic, rendering, or decision-making.

Backend and full-stack engineers designing or changing REST APIs, GraphQL schemas, module boundaries, or component prop interfaces who want a shared, opinionated contract - naming, error shape, versioning discipline - instead of re-litigating those choices for every endpoint or every team.