HTTP API 设计指南（结尾）

为了保证持续和及时的更新，强烈推荐在个人Github上关注该项目，欢迎各位star/fork或者帮助翻译

前言

这篇指南介绍描述了 HTTP+JSON API 的一种设计模式，最初摘录整理自 Heroku 平台的 API 设计指引 Heroku 平台 API 指引。

这篇指南除了详细介绍现有的 API 外，Heroku 未来新加入的内部 API 也会符合这种设计模式，咱们但愿非 Heroku 员工的API设计者也能感兴趣。

咱们的目标是保持一致性，专一业务逻辑同时避免过分设计。咱们一直试图找出一种良好的、一致的、显而易见的 API 设计方法，而并非所谓的"最终/理想模式"。

咱们假设你熟悉基本的 HTTP+JSON API 设计方法，因此本篇指南并不包含全部的 API 设计基础。

咱们欢迎你为这篇指南作贡献。

---

提供机器可读的JSON模式

提供一个机器可读的模式来恰当的表现你的API。使用
prmd管理你的模式，而且确保用prmd verify验证是有效的。

提供人类可读的文档

提供人类可读的文档让客户端开发人员能够理解你的API。

若是你用prmd建立了一个概要而且按上述要求描述，你能够为全部节点很容易的使用prmd doc生成Markdown文档。

除了节点信息，提供一个API概述信息:

• 验证受权，包含如何取得和如何使用token。

• API稳定及版本管理，包含如何选择所须要的版本。

• 通常状况下的请求和响应的头信息。

• 错误的序列化格式。

• 不一样编程语言客户端使用API的例子。

提供可执行的例子

提供可执行的示例让用户能够直接在终端里面看到API的调用状况，最大程度的让这些示例能够简单的使用，以减小用户尝试使用API的工做量。例如:

$ export TOKEN=... # acquire from dashboard
$ curl -is https://$TOKEN@service.com/users

若是你使用prmd生成Markdown文档，每一个节点都会自动获取一些示例。

描述稳定性

描述您的API的稳定性或是它在各类各样节点环境中的完备性和稳定性，例如：加上 原型版（prototype）/开发版（development）/产品版（production）等标记。

更多关于可能的稳定性和改变管理的方式，查看 Heroku API compatibility policy

一旦你的API宣布产品正式版本及稳定版本时，不要在当前API版本中作一些不兼容的改变。若是你须要，请建立一个新的版本的API。