鍍金池/ 教程/ Linux/ 可讀性
良好打印的默認 JSON
強制使用安全連接(Secure Connections)
通過請求中的范圍(Range)拆分大的響應(yīng)
嵌套外鍵關(guān)系
支持方便的無 id 間接引用
使用 UTC(世界標準時間)時間,用 ISO8601 進行格式化
提供標準的時間戳
提供資源的(UU)ID
提供全部可用的資源
描述穩(wěn)定性
路徑和屬性要小寫
強制頭信息 Accept 中提供版本號
生成結(jié)構(gòu)化的錯誤
使用統(tǒng)一的資源路徑格式
支持 Etag 緩存
保證響應(yīng) JSON 最小化
在請求的 body 體使用 JSON 格式數(shù)據(jù)
隔離關(guān)注點
顯示頻率限制狀態(tài)
提供可執(zhí)行的例子
返回合適的狀態(tài)碼
最小化路徑嵌套
可讀性
為內(nèi)省而提供 Request-Id

可讀性

機器可讀的 JSON 模式

提供一個機器可讀的模式可以精確的指定你的 API。使用 prmd 來管理你的模式,并確保它能被prmd verify 驗證。

人類可讀的文檔

提供人類可讀的文檔讓客戶端開發(fā)人員可以理解你的 API。

如果你用 prmd 創(chuàng)建了一個概要并且按上述要求描述,你可以為所有節(jié)點很容易的使用prmd doc生成 Markdown文檔。

除了節(jié)點信息,提供一個 API 概述信息:

  • 驗證授權(quán),包含如何取得和如何使用 token。
  • API 穩(wěn)定及版本管理,包含如何選擇所需要的版本。
  • 一般情況下的請求和響應(yīng)的頭信息。
  • 錯誤的序列化格式。
  • 不同編程語言客戶端使用 API 的例子。