# API and Interface Design (api-and-interface-design)

> Guides stable, hard-to-misuse APIs and module interfaces: contract first, consistent errors, validation at boundaries and additive changes.

- Category: [Architecture](https://www.myskills.tools/en/categories/architecture/)
- Source: Community · Addy Osmani
- Repository: https://github.com/addyosmani/agent-skills/tree/main/skills/api-and-interface-design (commit 63128d0)
- SKILL.md: https://github.com/addyosmani/agent-skills/blob/main/skills/api-and-interface-design/SKILL.md
- Install command: `npx skills add addyosmani/agent-skills --skill api-and-interface-design`
- License: MIT
- Compatible with: Claude Code, Codex, Cursor, Copilot, Gemini CLI
- Permissions: read-repo ✓, write-files ✓, shell ✗, network ✗
- Status: Scan passed
- A rule scan cannot catch every risk. Read this skill's SKILL.md and check its permissions before installing.

## Core rule

Hyrum's Law: every observable behavior will be depended on, so be intentional about what you expose.

## Execution Phases

1. **Contract first** — Define typed input and output interfaces before implementing; the contract is the spec.
2. **Errors and validation** — Use one error format everywhere, validate only at system boundaries, and treat third-party API responses as untrusted.
3. **Design for extension** — Add optional fields rather than changing or removing them, follow the one-version rule and consistent naming, and paginate list endpoints.
4. **Honour idempotency keys** — Derive keys from intent, claim them atomically with a unique constraint, reject a reused key with a different body, and retain keys past the longest retry path.
5. **Verify with the checklist** — Confirm typed inputs and outputs on every endpoint, one error format, backward-compatible changes, and types or docs committed with the implementation.

## Permissions (summarised from SKILL.md)

| Capability | Needed | Details |
|---|---|---|
| File writes | Required | Writes interface types, schemas, API handler code and accompanying docs. |
| Command execution | Not required | The skill does not call for running commands. |
| Network outbound | Not required | No network access. |

## SKILL.md frontmatter (YAML)

```yaml
---
name: api-and-interface-design
description: Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend.
---
```

Home: https://www.myskills.tools/en/ · URL: https://www.myskills.tools/en/skills/api-and-interface-design/