## 提供機器可讀的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)