## 工件（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。