請求

返回適當(dāng)?shù)臓顟B(tài)碼

為每個請求返回適當(dāng)?shù)臓顟B(tài)碼，成功的請求應(yīng)該遵守如下規(guī)則：

• 200: 當(dāng)GET請求成功完成，DELETE或者PATCH請求同步完成。
• 201: 同步方式成功完成POST請求。
• 202: POST，DELETE或者PATCH請求提交成功，稍后將異步的進(jìn)行處理。
• 206: GET請求成功完成，但只返回了部分?jǐn)?shù)據(jù)。參見用ranges分頁

注意認(rèn)證和認(rèn)證錯誤的使用：

• 401 Unauthorized: 請求失敗，因?yàn)橛脩魶]有進(jìn)行認(rèn)證。

• 403 Forbidden: 請求失敗，因?yàn)橛脩舯徽J(rèn)定沒有訪問特定資源的權(quán)限。
  返回合適的狀態(tài)碼可以為錯誤提供更多的信息：

• 422 Unprocessable Entity: 你的請求服務(wù)器可以理解，但是其中包含了不合法的參數(shù)。
• 429 Too Many Requests: 請求頻率超配，稍后再試。
• 500 Internal Server Error: 服務(wù)器出錯了，檢查網(wǎng)站的狀態(tài)，或者報(bào)告問題。

根據(jù)HTTP response code 規(guī)范的指導(dǎo)來設(shè)計(jì)用戶錯誤和服務(wù)器錯誤情況下的狀態(tài)碼。

總是返回完整的資源

對于200和201的響應(yīng)，總是盡可能在響應(yīng)中返回完整的資源（比如一個對象的所有屬性），包括PUT，PATCH和DELETE請求，如：

$ curl -X DELETE \  
  https://service.com/apps/1f9b/domains/0fd4

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
...
{
  "created_at": "2012-01-01T12:00:00Z",
  "hostname": "subdomain.example.com",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "updated_at": "2012-01-01T12:00:00Z"
}

202響應(yīng)則不用包含完整的資源，如:

$ curl -X DELETE \  
  https://service.com/apps/1f9b/dynos/05bd

HTTP/1.1 202 Accepted
Content-Type: application/json;charset=utf-8
...
{}

在請求body中接收J(rèn)SON序列

不要將額外信息放到form-encoded里邊，而是將其JSON序列放到PUT，PATCH或POST請求的Body中。這樣才能和同為JSON序列的響應(yīng)Body對稱（作者你是處女座么），如：

$ curl -X POST https://service.com/apps \
    -H "Content-Type: application/json" \
    -d '{"name": "demoapp"}'

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "demoapp",
  "owner": {
    "email": "username@example.com",
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  ...
}

使用一致的路徑格式

資源名稱

使用復(fù)數(shù)來命名資源，除非該資源在系統(tǒng)中是單件（比如，在絕大多數(shù)系統(tǒng)中，一個用戶只能擁有一個賬戶）。這樣在你引用特定資源時(shí)可以保持一致性。

動作

對獨(dú)有的資源使用不需要特定動作的endpoint格式。這樣當(dāng)需要特定的動作，只需要把它們放到標(biāo)準(zhǔn)的actions前綴后邊，就可以清晰的描述它們：

/resources/:resource/actions/:action

如：

/runs/{run_id}/actions/stop

小寫所有路徑和屬性

使用小寫字母和減號命名路徑，這樣Hostname可以對齊（作者你真的是處女座）：

service-api.com/users
service-api.com/app-setups

同樣小寫屬性，但使用下劃線來分割，這樣屬性名在JavaScript中可以不用加引號：

service_class: "first"

支持非ID的參數(shù)作為快捷方式

有時(shí)候要求最終用戶提供ID來表示資源會比較麻煩，比如，用戶可能只想得起Heroku的Appname，而應(yīng)用本身卻是由UUID來區(qū)分的。在這種情況下，我們可以同時(shí)接收ID和Name：

$ curl https://service.com/apps/{app_id_or_name}
$ curl https://service.com/apps/97addcf0-c182
$ curl https://service.com/apps/www-prod

絕不要只接收名稱來排除某些ID。

少用路徑嵌套

在嵌套了父子資源的數(shù)據(jù)模型中，路徑可能深度嵌套：

/orgs/{org_id}/apps/{app_id}/dynos/{dyno_id}

可以通過從根路徑定位來限制嵌套層數(shù)。使用嵌套來標(biāo)識作用域內(nèi)部的數(shù)據(jù)集。比如，上邊那個dyno屬于一個app，而app又屬于一個org的例子：

/orgs/{org_id}
/orgs/{org_id}/apps
/apps/{app_id}
/apps/{app_id}/dynos
/dynos/{dyno_id}