## 基礎 ### 隔離關注點 設計時通過將請求和響應之間的不同部分隔離來讓事情變得簡單。保持簡單的規則讓我們能更關注在一些更大的更困難的問題上。 請求和響應將解決一個特定的資源或集合。使用路徑（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](https://devcenter.heroku.com/articles/platform-api-reference#ranges).