## 返回適當的狀態碼
為每個請求返回適當的狀態碼，成功的請求應該遵守如下規則：
* 200: 當GET請求成功完成，DELETE或者PATCH請求同步完成。
* 201: 同步方式成功完成POST請求。
* 202: POST，DELETE或者PATCH請求提交成功，稍后將異步的進行處理。
* 206: GET請求成功完成，但只返回了部分數據。參見用[ranges分頁](https://github.com/easychen/http-api-design/tree/cn#paginate-with-ranges)
注意認證和認證錯誤的使用：
* 401 Unauthorized: 請求失敗，因為用戶沒有進行認證。
* 403 Forbidden: 請求失敗，因為用戶被認定沒有訪問特定資源的權限。
返回合適的狀態碼可以為錯誤提供更多的信息：
* 422 Unprocessable Entity: 你的請求服務器可以理解，但是其中包含了不合法的參數。
* 429 Too Many Requests: 請求頻率超配，稍后再試。
* 500 Internal Server Error: 服務器出錯了，檢查網站的狀態，或者報告問題。
根據[HTTP response code ](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)規范的指導來設計用戶錯誤和服務器錯誤情況下的狀態碼。
## 總是返回完整的資源
對于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"
},
...
}
~~~
## 使用一致的路徑格式
**資源名稱**
使用復數來命名資源，除非該資源在系統中是單件（比如，在絕大多數系統中，一個用戶只能擁有一個賬戶）。這樣在你引用特定資源時可以保持一致性。
**動作**
對獨有的資源使用不需要特定動作的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的參數作為快捷方式
有時候要求最終用戶提供ID來表示資源會比較麻煩，比如，用戶可能只想得起Heroku的Appname，而應用本身卻是由UUID來區分的。在這種情況下，我們可以同時接收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。
## 少用路徑嵌套
在嵌套了父子資源的數據模型中，路徑可能深度嵌套：
~~~
/orgs/{org_id}/apps/{app_id}/dynos/{dyno_id}
~~~
可以通過從根路徑定位來限制嵌套層數。使用嵌套來標識作用域內部的數據集。比如，上邊那個dyno屬于一個app，而app又屬于一個org的例子：
~~~
/orgs/{org_id}
/orgs/{org_id}/apps
/apps/{app_id}
/apps/{app_id}/dynos
/dynos/{dyno_id}
~~~
