提供機器可讀的JSON格式

提供機器可讀的schema來描述你的API，可以用prmd來管理你的schema，用過prmd verify來確保它通過驗證。

提供人類可讀的文檔

提供人類可讀的文檔幫助客戶端開發(fā)者們理解你的API。

如果你使用了prmd來創(chuàng)建schema，那么你可以簡單的通過prmd doc命令來生成Markdown的endpoint級別的文檔。

除了endpoint級別的描述，還要提供概要級別的信息，比如：

• 授權(quán)，包括獲得和使用授權(quán)Token。
• API的穩(wěn)定性和版本，包括如何選擇現(xiàn)有的API版本。
• 通用請求和響應(yīng)頭。
• 錯誤的序列化格式。
• 各種語言的客戶端如何使用API的例子。

  提供可執(zhí)行的示例

提供可執(zhí)行的例子，這樣用戶可以直接在終端輸入并看到可以用的API請求。最好的情況是，這些例子可以直接復(fù)制粘貼，以最小化用戶試用API的成本，如：

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

如果你使用prmd來生成Markdown文檔，你就免費獲得了可執(zhí)行的示例。

描述穩(wěn)定性

描述你API的穩(wěn)定性，以及哪些endpoint依賴于其成熟度，比如使用prototype，development或者production的標識。

可參考 Heroku API compatibility policy 了解哪些接口是穩(wěn)定的，哪些可能有變動。

一旦你的API宣布為 production-ready 和 穩(wěn)定版，不要在該API版本上做任何不向前兼容的修改。如果你需要做不向前兼容的修改，創(chuàng)建一個新的版本號。

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