Design stable, well-documented APIs and interfaces

This skill guides the design of stable, well-documented interfaces that are hard to misuse. The guiding idea is that a good interface makes the right thing easy and the wrong thing hard. It applies to REST APIs, GraphQL schemas, module boundaries, component props and any surface where one piece of code talks to another.

The core principles are:

• Hyrum's Law: with enough users, every observable behavior, including undocumented quirks, error message text, timing and ordering, becomes a de facto contract. So be intentional about what you expose, do not leak implementation details, and plan deprecation at design time. Contract tests alone do not protect against this.
• The One-Version Rule: avoid making consumers choose between versions of the same dependency or API, because that creates diamond dependency problems. Extend rather than fork.
• Contract first: define the interface before implementing it. The contract is the spec and the implementation follows.
• Consistent error semantics: pick one error strategy and use it everywhere. A REST example uses HTTP status codes with one structured error body (code, message, optional details), mapping 400 to invalid data, 401 to unauthenticated, 403 to unauthorized, 404 to not found, 409 to conflicts, 422 to semantic validation failure and 500 to server errors without internal details.
• Validate at boundaries: trust internal code and validate where external input enters, such as route handlers, form handlers, third-party response parsing and environment variable loading. Third-party API responses are untrusted data. Do not validate between internal functions that share type contracts or on data that just came from your own database.
• Prefer addition over modification: add optional fields instead of changing field types or removing fields.
• Predictable naming: plural nouns without verbs for REST endpoints, camelCase for query parameters and response fields, is/has/can prefixes for booleans and UPPER_SNAKE for enum values.

Use it when designing new API endpoints, defining module boundaries or contracts between teams, creating component prop interfaces, designing a database schema that informs API shape, or changing an existing public interface.

Do not treat it as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions. Use it only when the task clearly matches its upstream source and local project context, and verify commands, generated code, dependencies and credentials before applying changes. Its red flags are a useful audit list: endpoints returning different shapes depending on conditions, inconsistent error formats, validation scattered through internal code, breaking changes to existing fields, list endpoints without pagination, and verbs in REST URLs.

The input is a design task: an endpoint, a module boundary, a schema or a prop interface. The output is a typed contract and a set of conventions rather than running code. The skill covers REST patterns, including plural resource routes with PATCH for partial updates and sub-resources such as comments under a task. Lists are paginated with page, page size, sort by and sort order, and the response carries a pagination object with total items and total pages. Filters go in query parameters:

GET /api/tasks?status=in_progress&assignee=user123&createdAfter=2025-01-01

For TypeScript it recommends discriminated unions for variants so consumers get type narrowing, separate input and output types (server-generated fields such as id, createdAt and updatedAt appear only in output), and branded types for IDs so a user ID cannot be passed where a task ID is expected.

It ends with a verification checklist: every endpoint has typed input and output schemas, errors follow one format, validation happens at system boundaries only, list endpoints paginate, new fields are additive and optional, naming is consistent, and API documentation or types are committed alongside the implementation. A table of common rationalizations counters excuses such as documenting later, skipping pagination, using PUT instead of PATCH, or versioning only when needed.

It refers to a related skill, deprecation-and-migration, for safely removing behavior that users depend on. Its examples are written in TypeScript and cover REST and GraphQL style interfaces.

Backend and frontend developers, API designers and tech leads who define public interfaces or contracts between modules and teams, and want a consistent, backward-compatible approach to naming, errors, pagination and validation.