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

爲了保證持續和及時的更新，強烈推薦在個人Github上關注該項目，歡迎各位star/fork或者幫助翻譯

前言

這篇指南介紹描述了 HTTP+JSON API 的一種設計模式，最初摘錄整理自 Heroku 平臺的 API 設計指引 Heroku 平臺 API 指引。

這篇指南除了詳細介紹現有的 API 外，Heroku 未來新加入的內部 API 也會符合這種設計模式，咱們但願非 Heroku 員工的API設計者也能感興趣。

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

咱們假設你熟悉基本的 HTTP+JSON API 設計方法，因此本篇指南並不包含全部的 API 設計基礎。

咱們歡迎你爲這篇指南作貢獻。

---

隔離關注點

設計時經過將請求和響應之間的不一樣部分隔離來讓事情變得簡單。保持簡單的規則讓咱們能更關注在一些更大的更困難的問題上。

請求和響應將解決一個特定的資源或集合。使用路徑（path）來代表身份，body來傳輸內容（content）還有頭信息（header）來傳遞元數據（metadata）。查詢參數一樣能夠用來傳遞頭信息的內容，但頭信息是首選，由於他們更靈活、更能傳達不一樣的信息。

強制使用安全鏈接（Secure Connections）

全部的訪問API行爲，都須要用 TLS 經過安全鏈接來訪問。沒有必要搞清或解釋什麼狀況須要 TLS 什麼狀況不須要 TLS，直接強制任何訪問都要經過 TLS。

理想狀態下，經過拒絕全部非 TLS 請求，不響應 http 或80端口的請求以免任何不安全的數據交換。若是現實狀況中沒法這樣作，能夠返回403 Forbidden響應。

把非 TLS 的請求重定向(Redirect)至 TLS 鏈接是不明智的，這種含混/很差的客戶端行爲不會帶來明顯好處。依賴於重定向的客戶端訪問不只會致使雙倍的服務器負載，還會使 TLS 加密失去意義，由於在首次非 TLS 調用時，敏感信息就已經暴露出去了。

強制頭信息 Accept 中提供版本號

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

爲了不API的變更致使用戶使用中產生意外結果或調用失敗，最好強制要求全部訪問都須要指定版本號。請避免提供默認版本號，一旦提供，往後想要修改它會至關困難。

最適合放置版本號的位置是頭信息(HTTP Headers)，在 Accept 段中使用自定義類型(content type)與其餘元數據(metadata)一塊兒提交。例如:

Accept: application/vnd.heroku+json; version=3

支持Etag緩存

在全部返回的響應中包含ETag頭信息，用來標識資源的版本。這讓用戶對資源進行緩存處理成爲可能，在後續的訪問請求中把If-None-Match頭信息設置爲以前獲得的ETag值，就能夠偵測到已緩存的資源是否須要更新。

爲內省而提供 Request-Id

爲每個請求響應包含一個Request-Id字段，並使用UUID做爲該值。經過在客戶端、服務器或任何支持服務上記錄該值，它能主咱們提供一種機制來跟蹤、診斷和調試請求。

經過請求中的範圍（Range）拆分大的響應

一個大的響應應該經過多個請求使用Range頭信息來拆分，並指定如何取得。詳細的請求和響應的頭信息（header），狀態碼(status code)，範圍(limit)，排序(ordering)和迭代(iteration)等，參考Heroku Platform API discussion of Ranges.