RESTful API 设计：资源、语义与错误

API 设计要先约定资源、操作和失败的含义，再考虑路径的命名。这里从原有后台接口笔记中保留可复用的设计要点，修正把 HTTP 操作直接等同于 SQL 的说法。

资源与操作

/projects 可以表示项目集合，/projects/123 表示一个项目。复数名词是一种一致的命名约定，不是协议强制要求；资源也不必对应一张数据库表。

GET 用于读取，HEAD 获取相应的响应头而不返回内容；POST 交由资源处理，PUT 创建或替换目标资源的状态，DELETE 请求移除目标资源与当前功能的关联。OPTIONS 描述通信选项，不是查询哪些数据库字段可以编辑。具体语义见 HTTP Semantics。

PATCH 表达部分修改。补丁格式需要明确，例如“把计数改成 3”与“把计数增加 3”具有不同的重试效果；PATCH 本身不保证幂等。RFC 5789

安全方法的请求语义不要求改变资源状态；幂等指重复请求的预期效果与执行一次相同，不保证响应相同。第一次 DELETE 成功、第二次返回 404，并不因此破坏幂等性。状态码本身不能决定一个业务操作是否幂等。

状态与错误

成功、创建、接受处理和没有响应内容，是不同的结果：200 表示成功；201 用于创建；202 只表示接受请求，不能当作任务完成；204 不携带响应内容。认证凭据缺失或无效常用 401，拒绝处理用 403，404 表示未找到或不愿披露存在。冲突和无法处理的内容可分别用 409、422 表达。状态码定义

不要把所有业务失败都包装成 200，让调用方只能猜正文。错误响应应有稳定的机器可读代码、可理解的说明，以及必要的字段信息，例如：

{
  "code": "validation_failed",
  "message": "项目名称不能为空",
  "errors": [{"field": "name", "code": "required"}]
}

详细错误不等于暴露服务器内部信息。客户端需要知道如何修正请求，内部堆栈则留给日志和排查。

一致的约定

过滤、排序、分页、版本和字段命名要在各个接口间保持一致。列表响应除了数据，还应清楚表达下一页如何获取；修改响应是否返回最新对象，也应写进文档。响应中提供下一步可用的链接，可以减少调用方拼接路径的工作，但不能代替完整的接口文档。

通信使用 HTTPS。认证、授权与资源访问规则需要单独设计，不能仅凭“客户端”或“服务端”分类就决定认证方案。原笔记中的 JSONP、URL 携带令牌和旧认证接口示例不再保留。

最后，把异步任务、重试、限流和超时也视为接口契约的一部分。限流字段要明确窗口、剩余额度与重试时间的单位，不能把请求配额写成并发连接数。与其让客户端猜测，不如提供能运行的正常和失败示例。