工件
最后更新于:2022-04-01 04:39:56
## 工件(Artifacts)
### 提供机器可读的JSON模式
提供一个机器可读的模式来恰当的表现你的API。使用 [prmd](https://github.com/interagent/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](https://github.com/interagent/prmd)生成Markdown文档,每个节点都会自动获取一些示例。
### 描述稳定性
描述您的API的稳定性或是它在各种各样节点环境中的完备性和稳定性,例如:加上 原型版(prototype)/开发版(development)/产品版(production)等标记。
更多关于可能的稳定性和改变管理的方式,查看 [Heroku API compatibility policy](https://devcenter.heroku.com/articles/api-compatibility-policy)
一旦你的API宣布产品正式版本及稳定版本时,不要在当前API版本中做一些不兼容的改变。如果你需要,请创建一个新的版本的API。