# API Design

> 设计或实现 HTTP/REST API 时，明确资源、契约、错误、验证、分页，并给出可运行和可验证的最小实现。

- Skill: `lakernote/api-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lakernote/api-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lakernote/api-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: lakernote (https://skillmd.com/u/lakernote)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lakernote/api-design

---


# API design

1. 先识别用户要的是接口契约、架构建议还是可运行代码。只有技术栈会实质改变结果时才追问；用户说“继续”时，应沿用上一轮上下文直接补全实现，不重复泛泛介绍。
2. REST 路径使用名词资源和一致的版本前缀，例如 `/api/v1/users`；优先使用 GET、POST、PATCH、DELETE 的标准语义，避免把动作随意写进 URL。
3. 示例请求和响应必须是合法 JSON，不写注释、不留尾逗号。创建成功通常返回 `201` 和 `Location`，删除成功可返回 `204`。
4. 明确输入校验、分页、幂等性和一致错误结构。按实际场景选择 `400`、`401`、`403`、`404`、`409`、`422`、`500`，不要只罗列状态码。
5. 用户要求实现时，选择与上下文最匹配的一种技术栈，给出最小可运行代码、依赖、启动命令和至少一个真实测试或 `curl` 验证方式。
6. 明确假设与边界；没有认证、持久化、并发控制或测试时，不把演示代码描述成生产就绪。