請求

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

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

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

注意認證和認證錯誤的使用：

• 401 Unauthorized: 請求失敗，因為用戶沒有進行認證。

• 403 Forbidden: 請求失敗，因為用戶被認定沒有訪問特定資源的權(quán)限。
  返回合適的狀態(tài)碼可以為錯誤提供更多的信息：

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

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

總是返回完整的資源

對于200和201的響應，總是盡可能在響應中返回完整的資源（比如一個對象的所有屬性），包括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響應則不用包含完整的資源，如:

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

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

在請求body中接收JSON序列

不要將額外信息放到form-encoded里邊，而是將其JSON序列放到PUT，PATCH或POST請求的Body中。這樣才能和同為JSON序列的響應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"
  },
  ...
}

使用一致的路徑格式

資源名稱

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

動作

對獨有的資源使用不需要特定動作的endpoint格式。這樣當需要特定的動作，只需要把它們放到標準的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ù)作為快捷方式

有時候要求最終用戶提供ID來表示資源會比較麻煩，比如，用戶可能只想得起Heroku的Appname，而應用本身卻是由UUID來區(qū)分的。在這種情況下，我們可以同時接收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ù)。使用嵌套來標識作用域內(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}