Heroku的HTTP API設計指南

Wesley Beary是Heroku API團隊的成員，他整理了一份用於建立HTTP+JSON API的指南，並以非常精煉的語言對該指南進行了陳述。

該指南以若干條建議開始：

• 需要所有的API呼叫都使用TLS。針對非TLS的呼叫以403 Forbidden進行回應
• 始終對API進行版本化。使用Accept 頭部來指定版本。需要客戶端指定API版本，而不是簡單地以預設版本進行回應。
• 使用ETag 頭部來支援資源的快取
• 識別出每個具有X-Request-ID的響應；這對達成日誌跟蹤或除錯等目的會非常有用
• 使用Range, Content-Range, Next-Range 來處理資料量較大的響應

針對發出的請求，該指南提到了如下幾點：

• 返回合適的狀態碼，例如200: 成功的 GET 或 同步的DELETE, PATCH201: 成功且同步的POST
  …401: 未經授權的呼叫429: 請求頻率超過限制等等。
• 當可用時總是返回完整的資源
• 接受請求中那些與JSON響應對稱的序列化JSON
• 使用一致的路徑格式。除非特指單例，否則資源名稱應該使用複數的形式
• 路徑和屬性都使用小寫字母，從而與主機名保持對齊
• 允許為某些資源指定除UUID以外的名稱，例如像應用的名稱
• 嘗試通過儘可能將資源配置到離根路徑較近的路徑位置來限制資源巢狀的深度

當談到關於響應的部分，Beary建議如下：

• 為每個資源使用全域性唯一的ID
• 為資源提供標準的時間戳
• 針對時間戳，應該使用格式為ISO8601的UTC時間
• 將外來鍵關係嵌入到當前資源從而可以包含更多關聯資源的詳情，並且無須修改響應的結構，
• 提供詳細的錯誤資訊，包括一個機器可讀的ID、一段人類可讀的錯誤訊息以及一個可選的指向更多細節的URL
• 設定一個請求頻率限制，然後可以使用一個像RateLimit-Remaining這樣的頭部來在每個響應中告知客戶端可用請求令牌的剩餘請求數量
• 應該對所有響應中的JSON進行壓縮

該指南還包括了更多的相關忠告：

• 以機器可讀的格式提供JSON schema
• 包括為開發者而準備的詳細的API文件
• 允許開發者測試API
• API應該根據它們的穩定性狀態分別標記為：原型（prototype）/開發（development）/生產（production）

我們就如何總結出這些指南以及如何對它們中的部分進行解釋向Beary進行了採訪。

InfoQ:你從一開始就擁有一份API設計指南嗎？

WB: 我從早期就擁有了一部分指南，但是它們都相當地粗糙，且僅僅存在於我的腦海之中。自從我開始 github.com/fog/fog上及其相關的工作以來，我已經消費過很多不同的API，這幫助我近一步形成了這些觀點。

InfoQ:如果你一開始沒有這些指南，那麼你是如何開發API的？通過不斷的迭代嗎？

WB: 因為缺乏一個更加正式的指南，這無疑會是一個迭代的過程。不幸的是，除了有點慢之外，迭代的過程也是無法伸縮的，它成為了我向API新增內容的障礙。所以我們構建了該指南來推動這些決策制定的分發工作。我們會繼續進行迭代，但是就指南本身而言通常現在也處於迭代之中。我們可以看到有很多正在進行中的討論（github.com/interagent/http-api-design/issues），伴隨著我們學習到更多的經驗以及其他開發者對這些指南的採用，這些討論將持續對我們的這個文件進行闡明和發展。

InfoQ:為什麼建議在針對PUT或DELETE操作時返回整個資源？

WB:異常情況是介面和指南中的對立部分。有時客戶端期望得到整個資源，而出於對優化的考慮我們通常會對客戶端的這種期望不加理會。我認為可以將該行為視為是可選的，通常可選的行為在很多場景中都是有意義的，但是具備一個簡單、有用的預設選項是有價值的。也就是說，這是一個有爭議的觀點，而在 https://github.com/interagent/http-api-design/issues/9上可以找到一些正在進行中的討論，它們對這個觀點的優缺點進行了更加深入地探討。

InfoQ:為什麼只使用ISO8601格式的UTC時間？

WB:這與返回整個資源相似，具有一致的規則（不考慮異常）可以更容易地對你正在做的事情進行思考，從而減少你在設計某些事物的時候需要做出決策的次數。同樣的，時區是瘋狂而可怕的。我已經記不清我所遇到或引起的與時區相關的錯誤次數了。為了有望減少問題，我們選擇了一個我們所熟知的時區和格式來在各方面進行使用。

檢視英文原文：Heroku’s HTTP API Design Guide