文檔及其它

提供機(jī)器可讀的JSON格式

提供機(jī)器可讀的schema來(lái)描述你的API，可以用prmd來(lái)管理你的schema，用過(guò)prmd verify來(lái)確保它通過(guò)驗(yàn)證。

提供人類可讀的文檔

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

如果你使用了prmd來(lái)創(chuàng)建schema，那么你可以簡(jiǎn)單的通過(guò)prmd doc命令來(lái)生成Markdown的endpoint級(jí)別的文檔。

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

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

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

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

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

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

描述穩(wěn)定性

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

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

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

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