API Design
Design interfaces that are hard to misuse.
Install 安装
curl -sSL https://updating.cc/skills/engineering-team/api-design/SKILL.md -o ~/.agents/skills/engineering-team__api-design/SKILL.mdSKILL.md Preview 技能内容预览
---
name: API Design
description: Design interfaces that are hard to misuse.
---
# API Design
The quality of an API is measured by how rarely callers misuse it, not by how clever it is. Spend your effort on the boundary; internals can be ugly.
## Principles
- **Make wrong states unrepresentable.** If an endpoint requires field B whenever A="x", model that as two endpoints or a sum type — don't accept any combination and validate at runtime.
- **Few concepts, composable.** A small set of orthogonal primitives beats a large menu of overlapping ones.
- **Be explicit about failure.** Distinguish "not found", "forbidden", and "bad input" with different statuses/types. A single generic error forces callers to guess.
- **Version from day one** in a way you can actually honor later (path or header), because you will need to change something.
- **Names matter enormously.** `listOrdersSince(timestamp)` is unambiguous; `get(data, opt)` is not. Read your own signatures aloud.
## Consistency
Whatever you decide (pagination style, error envelope, auth), apply it everywhere. Inconsistency is the single most common reason callers write brittle glue code.