API Design

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

lakernote b218fb8 1.2 KB Updated

File contents

API design

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

lakernote/easy-agent/tree/main/internal/builtin/skills/definitions/api-design commit b218fb8a5f

Frequently asked questions

npx skillmds@latest add lakernote/api-design