## 提供机器可读的JSON格式 提供机器可读的schema来描述你的API,可以用[prmd](https://github.com/interagent/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](https://devcenter.heroku.com/articles/api-compatibility-policy) 了解哪些接口是稳定的,哪些可能有变动。 一旦你的API宣布为 production-ready 和 稳定版,不要在该API版本上做任何不向前兼容的修改。如果你需要做不向前兼容的修改,创建一个新的版本号。 英文原版 → [https://github.com/interagent/http-api-design](https://github.com/interagent/http-api-design)