## 總是提供資源(UU)ID
為每個(gè)資源提供默認(rèn)的ID屬性。除非有特殊理由，總是使用UUID。不要用那些在服務(wù)的實(shí)例間或資源間不全局唯一的ID，特別是自增ID。
以8-4-4-4-12的格式小寫(xiě)UUID：
~~~
"id": "01234567-89ab-cdef-0123-456789abcdef"
~~~
## 提供標(biāo)準(zhǔn)的時(shí)間戳
為資源提供默認(rèn)的 `created_at` 和 `updated_at` 時(shí)間戳：
~~~
{
...
"created_at": "2012-01-01T12:00:00Z",
"updated_at": "2012-01-01T13:00:00Z",
...
}
~~~
如果這些時(shí)間戳對(duì)某些資源真的沒(méi)有意義，那么你也可以去掉它。
## 使用ISO8601格式的UTC時(shí)間
只接受和返回UTC時(shí)間，以ISO8601格式顯示：
~~~
"finished_at": "2012-01-01T12:00:00Z"
~~~
## 嵌入外鍵數(shù)據(jù)
將外鍵引用通過(guò)序列化的嵌入對(duì)象顯示：
~~~
{
"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)化的錯(cuò)誤信息
為錯(cuò)誤生成一致的，結(jié)構(gòu)化的響應(yīng)Body。包含機(jī)器可讀的id，人類(lèi)可讀的message，以及可選的url指向關(guān)于錯(cuò)誤的更多信息，還有如何解決它：
~~~
HTTP/1.1 429 Too Many Requests
{
"id": "rate_limit",
"message": "Account reached its API rate limit.",
"url": "https://docs.service.com/rate-limits"
}
~~~
為客戶端常見(jiàn)的錯(cuò)誤的格式和id撰寫(xiě)文檔。
## 顯示頻率限制的狀態(tài)
對(duì)客戶端的頻率限制可以保護(hù)服務(wù)的健康，并對(duì)其他的客戶端提供高質(zhì)量的服務(wù)。你可以使用[token bucket](http://en.wikipedia.org/wiki/Token_bucket) 算法 來(lái)量化請(qǐng)求限制。
在每次請(qǐng)求的響應(yīng)頭中，通過(guò)RateLimit-Remaining 返回剩余的請(qǐng)求次數(shù)。
## 在所有的響應(yīng)中壓縮JSON數(shù)據(jù)
額外的空格增大了響應(yīng)的大小，而很多人性化的客戶端可以自動(dòng)美化JSON輸出。所以最好將JSON響應(yīng)進(jìn)行壓縮：
`{"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"
}
~~~
你可以考慮提供一個(gè)可選的方式來(lái)為客戶端輸出更長(zhǎng)的響應(yīng)，比如通過(guò)請(qǐng)求參數(shù)（如`?pretty=true`）或者通過(guò) Accept頭（如`Accept: application/vnd.heroku+json; version=3; indent=4;`）。
AI寫(xiě)作智能體 自主規(guī)劃任務(wù)，支持聯(lián)網(wǎng)查詢和網(wǎng)頁(yè)讀取，多模態(tài)高效創(chuàng)作各類(lèi)分析報(bào)告、商業(yè)計(jì)劃、營(yíng)銷(xiāo)方案、教學(xué)內(nèi)容等。
![]()
廣告