HTTP API 設計指南（基礎部分）

這篇指南介紹描述了 http+json api 的一種設計模式，最初摘錄整理自 heroku 平台的 api 設計指引 heroku 平台 api 指引。

這篇指南除了詳細介紹現有的 api 外，heroku 將來新加入的內部 api 也會符合這種設計模式，我們希望非 heroku 員工的api設計者也能感興趣。

我們的目標是保持一致性，專注業務邏輯同時避免過度設計。我們一直試圖找出一種良好的、一致的、顯而易見的 api 設計方法，而並不是所謂的"最終/理想模式"。

我們假設你熟悉基本的 http+json api 設計方法，所以本篇指南並不包含所有的 api 設計基礎。

我們歡迎你為這篇指南做貢獻。

請求和響應將解決乙個特定的資源或集合。使用路徑（path）來表明身份，body來傳輸內容（content）還有頭資訊（header）來傳遞元資料（metadata）。查詢引數同樣可以用來傳遞頭資訊的內容，但頭資訊是首選，因為他們更靈活、更能傳達不同的資訊。

所有的訪問api行為，都需要用 tls 通過安全連線來訪問。沒有必要搞清或解釋什麼情況需要 tls 什麼情況不需要 tls，直接強制任何訪問都要通過 tls。

理想狀態下，通過拒絕所有非 tls 請求，不響應 http 或80埠的請求以避免任何不安全的資料交換。如果現實情況中無法這樣做，可以返回403 forbidden響應。

把非 tls 的請求重定向(redirect)至 tls 連線是不明智的，這種含混/不好的客戶端行為不會帶來明顯好處。依賴於重定向的客戶端訪問不僅會導致雙倍的伺服器負載，還會使 tls 加密失去意義，因為在首次非 tls 呼叫時，敏感資訊就已經暴露出去了。

制定版本並在版本之間平緩過渡對於設計和維護一套api是個巨大的挑戰。所以，最好在設計之初就使用一些方法來預防可能會遇到的問題。

為了避免api的變動導致使用者使用中產生意外結果或呼叫失敗，最好強制要求所有訪問都需要指定版本號。請避免提供預設版本號，一旦提供，日後想要修改它會相當困難。

最適合放置版本號的位置是頭資訊(http headers)，在accept段中使用自定義型別(content type)與其他元資料(metadata)一起提交。例如:

在所有返回的響應中包含etag頭資訊，用來標識資源的版本。這讓使用者對資源進行快取處理成為可能，在後續的訪問請求中把if-none-match頭資訊設定為之前得到的etag值，就可以偵測到已快取的資源是否需要更新。

為每乙個請求響應包含乙個request-id字段，並使用uuid作為該值。通過在客戶端、伺服器或任何支援服務上記錄該值，它能主我們提供一種機制來跟蹤、診斷和除錯請求。

乙個大的響應應該通過多個請求使用range頭資訊來拆分，並指定如何取得。詳細的請求和響應的頭資訊（header），狀態碼(status code)，範圍(limit)，排序(ordering)和迭代(iteration)等，參考heroku platform api discussion of ranges.

原文:

HTTP API 設計指南（基礎部分）

HTTP API 設計指南（基礎部分）

HTTP API 設計指南（響應部分）

HTTP API 設計指南（結尾）

HTTP API 設計指南（基礎部分）

HTTP API 設計指南（基礎部分）

HTTP API 設計指南（響應部分）

HTTP API 設計指南（結尾）

相關推薦