為了保證持續和及時的更新，強烈推薦在我的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）。查詢引數同樣可以用來傳遞頭資訊的內容，但頭資訊是首選，因為他們更靈活、更能傳達不同的資訊。
所有的訪問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 json api 的一種設計模式，最初摘錄整理自 heroku 平台的 api 設計指引 heroku 平台 api 指引。這篇指南除了詳細介紹現有的 api 外，heroku 將來新加入的內部 api 也會符合這種設計模式，我們希望非 heroku 員工的api設計者...
HTTP API 設計指南（響應部分）
這篇指南介紹描述了 http json api 的一種設計模式，最初摘錄整理自 heroku 平台的 api 設計指引 heroku 平台 api 指引。這篇指南除了詳細介紹現有的 api 外，heroku 將來新加入的內部 api 也會符合這種設計模式，我們希望非 heroku 員工的api設計者...
HTTP API 設計指南（結尾）
為了保證持續和及時的更新，強烈推薦在我的github上關注該專案，歡迎各位star fork或者幫助翻譯 這篇指南介紹描述了 http json api 的一種設計模式，最初摘錄整理自 heroku 平台的 api 設計指引 heroku 平台 api 指引。這篇指南除了詳細介紹現有的 api 外，...