響應(yīng)

總是提供資源(UU)ID

為每個資源提供默認的ID屬性。除非有特殊理由，總是使用UUID。不要用那些在服務(wù)的實例間或資源間不全局唯一的ID，特別是自增ID。

以8-4-4-4-12的格式小寫UUID：

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

提供標準的時間戳

為資源提供默認的 created_at 和 updated_at 時間戳：

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

如果這些時間戳對某些資源真的沒有意義，那么你也可以去掉它。

使用ISO8601格式的UTC時間

只接受和返回UTC時間，以ISO8601格式顯示：

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

嵌入外鍵數(shù)據(jù)

將外鍵引用通過序列化的嵌入對象顯示：

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

而不是這樣：

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

這使得我們可以在inline使用相關(guān)的數(shù)據(jù)，而不需要改變響應(yīng)的格式，或者引入更多高層的響應(yīng)字段：

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

總是生成結(jié)構(gòu)化的錯誤信息

為錯誤生成一致的，結(jié)構(gòu)化的響應(yīng)Body。包含機器可讀的id，人類可讀的message，以及可選的url指向關(guān)于錯誤的更多信息，還有如何解決它：

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撰寫文檔。

顯示頻率限制的狀態(tài)

對客戶端的頻率限制可以保護服務(wù)的健康，并對其他的客戶端提供高質(zhì)量的服務(wù)。你可以使用token bucket 算法 來量化請求限制。

在每次請求的響應(yīng)頭中，通過RateLimit-Remaining 返回剩余的請求次數(shù)。

在所有的響應(yīng)中壓縮JSON數(shù)據(jù)

額外的空格增大了響應(yīng)的大小，而很多人性化的客戶端可以自動美化JSON輸出。所以最好將JSON響應(yīng)進行壓縮：

{"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"
}

你可以考慮提供一個可選的方式來為客戶端輸出更長的響應(yīng)，比如通過請求參數(shù)（如?pretty=true）或者通過 Accept頭（如Accept: application/vnd.heroku+json; version=3; indent=4;）。