Heroku 的 HTTP API 设计指南

Wesley Beary 是 Heroku API 团队的成员，他整理了一份用于创建 HTTP+JSON API 的指南，并以非常精炼的语言对该指南进行了陈述。

该指南以若干条建议开始：

• 需要所有的 API 调用都使用 TLS。针对非 TLS 的调用以 403 Forbidden 进行回应
• 始终对 API 进行版本化。使用 Accept 头部来指定版本。需要客户端指定 API 版本，而不是简单地以默认版本进行回应。
• 使用 ETag 头部来支持资源的缓存
• 识别出每个具有 X-Request-ID 的响应；这对达成日志跟踪或调试等目的会非常有用
• 使用 Range, Content-Range, Next-Range 来处理数据量较大的响应

针对发出的请求，该指南提到了如下几点：

• 返回合适的状态码，例如 200: 成功的 GET 或 同步的 DELETE, PATCH

  201: 成功且同步的 POST
  …

  401: 未经授权的调用

  429: 请求频率超过限制

  等等。

• 当可用时总是返回完整的资源

• 接受请求中那些与 JSON 响应对称的序列化 JSON

• 使用一致的路径格式。除非特指单例，否则资源名称应该使用复数的形式

• 路径和属性都使用小写字母，从而与主机名保持对齐

• 允许为某些资源指定除 UUID 以外的名称，例如像应用的名称

• 尝试通过尽可能将资源配置到离根路径较近的路径位置来限制资源嵌套的深度

当谈到关于响应的部分，Beary 建议如下：

• 为每个资源使用全局唯一的 ID
• 为资源提供标准的时间戳
• 针对时间戳，应该使用格式为 ISO8601 的 UTC 时间
• 将外键关系嵌入到当前资源从而可以包含更多关联资源的详情，并且无须修改响应的结构，
• 提供详细的错误信息，包括一个机器可读的 ID、一段人类可读的错误消息以及一个可选的指向更多细节的 URL
• 设定一个请求频率限制，然后可以使用一个像 RateLimit-Remaining 这样的头部来在每个响应中告知客户端可用请求令牌的剩余请求数量
• 应该对所有响应中的 JSON 进行压缩

该指南还包括了更多的相关忠告：

• 以机器可读的格式提供 JSON schema
• 包括为开发者而准备的详细的 API 文档
• 允许开发者测试 API
• API 应该根据它们的稳定性状态分别标记为：原型（prototype）/ 开发（development）/ 生产（production）

我们就如何总结出这些指南以及如何对它们中的部分进行解释向 Beary 进行了采访。

InfoQ:你从一开始就拥有一份 API 设计指南吗？

WB: 我从早期就拥有了一部分指南，但是它们都相当地粗糙，且仅仅存在于我的脑海之中。自从我开始 github.com/fog/fog 上及其相关的工作以来，我已经消费过很多不同的 API，这帮助我近一步形成了这些观点。

InfoQ:如果你一开始没有这些指南，那么你是如何开发 API 的？通过不断的迭代吗？

WB: 因为缺乏一个更加正式的指南，这无疑会是一个迭代的过程。不幸的是，除了有点慢之外，迭代的过程也是无法伸缩的，它成为了我向 API 新增内容的障碍。所以我们构建了该指南来推动这些决策制定的分发工作。我们会继续进行迭代，但是就指南本身而言通常现在也处于迭代之中。我们可以看到有很多正在进行中的讨论（ github.com/interagent/http-api-design/issues ），伴随着我们学习到更多的经验以及其他开发者对这些指南的采用，这些讨论将持续对我们的这个文档进行阐明和发展。

InfoQ:为什么建议在针对 PUT 或 DELETE 操作时返回整个资源？

WB:异常情况是接口和指南中的对立部分。有时客户端期望得到整个资源，而出于对优化的考虑我们通常会对客户端的这种期望不加理会。我认为可以将该行为视为是可选的，通常可选的行为在很多场景中都是有意义的，但是具备一个简单、有用的默认选项是有价值的。也就是说，这是一个有争议的观点，而在 https://github.com/interagent/http-api-design/issues/9 上可以找到一些正在进行中的讨论，它们对这个观点的优缺点进行了更加深入地探讨。

InfoQ:为什么只使用 ISO8601 格式的 UTC 时间？

WB: 这与返回整个资源相似，具有一致的规则（不考虑异常）可以更容易地对你正在做的事情进行思考，从而减少你在设计某些事物的时候需要做出决策的次数。同样的，时区是疯狂而可怕的。我已经记不清我所遇到或引起的与时区相关的错误次数了。为了有望减少问题，我们选择了一个我们所熟知的时区和格式来在各方面进行使用。

查看英文原文： Heroku’s HTTP API Design Guide