文档及其它

提供机器可读的JSON格式

提供机器可读的schema来描述你的API，可以用prmd来管理你的schema，用过prmd verify来确保它通过验证。

提供人类可读的文档

提供人类可读的文档帮助客户端开发者们理解你的API。

如果你使用了prmd来创建schema，那么你可以简单的通过prmd doc命令来生成Markdown的endpoint级别的文档。

除了endpoint级别的描述，还要提供概要级别的信息，比如：

• 授权，包括获得和使用授权Token。
• API的稳定性和版本，包括如何选择现有的API版本。
• 通用请求和响应头。
• 错误的序列化格式。
• 各种语言的客户端如何使用API的例子。

  提供可执行的示例

提供可执行的例子，这样用户可以直接在终端输入并看到可以用的API请求。最好的情况是，这些例子可以直接复制粘贴，以最小化用户试用API的成本，如：

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

如果你使用prmd来生成Markdown文档，你就免费获得了可执行的示例。

描述稳定性

描述你API的稳定性，以及哪些endpoint依赖于其成熟度，比如使用prototype，development或者production的标识。

可参考 Heroku API compatibility policy 了解哪些接口是稳定的，哪些可能有变动。

一旦你的API宣布为 production-ready 和 稳定版，不要在该API版本上做任何不向前兼容的修改。如果你需要做不向前兼容的修改，创建一个新的版本号。

英文原版 → https://github.com/interagent/http-api-design