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

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

前言

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

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

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

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

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

---

提供資源的(UU)ID

在默認狀況給每個資源一個id屬性。除非有更好的理由，不然請使用UUID。不要使用那種在服務器上或是資源中不是全局惟一的標識，尤爲是自動增加的id。

生成小寫的UUID格式 8-4-4-4-12，例如：

"id": "01234567-89ab-cdef-0123-456789abcdef"

提供標準的時間戳

爲資源提供默認的建立時間 created_at 和更新時間 updated_at，例如:

{
  ...
  "created_at": "2012-01-01T12:00:00Z",
  "updated_at": "2012-01-01T13:00:00Z",
  ...
}

有些資源不須要使用時間戳那麼就忽略這兩個字段。

使用UTC（世界標準時間）時間，用ISO8601進行格式化

在接收和返回時都只使用UTC格式。ISO8601格式的數據，例如:

"finished_at": "2012-01-01T12:00:00Z"

嵌套外鍵關係

使用嵌套對象序列化外鍵關聯，例如:

{
  "name": "service-production",
  "owner": {
    "id": "5d8201b0..."
  },
  // ...
}

而不是像這樣:

{
  "name": "service-production",
  "owner_id": "5d8201b0...",
  ...
}

這種方式儘量的把相關聯的資源信息內聯在一塊兒，而不用改變資源的結構，或者引入更多的字段，例如:

{
  "name": "service-production",
  "owner": {
    "id": "5d8201b0...",
    "name": "Alice",
    "email": "alice@heroku.com"
  },
  ...
}

生成結構化的錯誤

響應錯誤的時，生成統一的、結構化的錯誤信息。包含一個機器可讀的錯誤 id，一我的類能識別的錯誤信息（message），根據狀況能夠添加一個url來告訴客戶端關於這個錯誤的更多信息以及如何去解決它，例如:

HTTP/1.1 429 Too Many Requests

{
  "id":      "rate_limit",
  "message": "Account reached its API rate limit.",
  "url":     "https://docs.service.com/rate-limits"
}

文檔化客戶端可能遇到的錯誤信息格式，以及這些可能的錯誤信息id。

顯示頻率限制狀態

客戶端的訪問速度限制能夠維護服務器的良好狀態，保證爲其餘客戶端請求提供高性的服務。你可使用token bucket algorithm技術量化請求限制。

爲每個帶有RateLimit-Remaining響應頭的請求，返回預留的請求tokens。

保證響應JSON最小化

請求中多餘的空格會增長響應大小，並且如今不少的HTTP客戶端都會本身輸出可讀格式（"prettify"）的JSON。因此最好保證響應JSON最小化，例如：

{"beta":false,"email":"alice@heroku.com","id":"01234567-89ab-cdef-0123-456789abcdef","last_login":"2012-01-01T12:00:00Z","created_at":"2012-01-01T12:00:00Z","updated_at":"2012-01-01T12:00:00Z"}

而不是這樣：

{
  "beta": false,
  "email": "alice@heroku.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "last_login": "2012-01-01T12:00:00Z",
  "created_at": "2012-01-01T12:00:00Z",
  "updated_at": "2012-01-01T12:00:00Z"
}

你能夠提供可選的方式爲客戶端提供更詳細可讀的響應，使用查詢參數（例如：?pretty=true）或者經過Accept頭信息參數（例如：Accept: application/vnd.heroku+json; version=3; indent=4;）