RESTful 是目前最流行的 API 設(shè)計規(guī)范，用于 Web 數(shù)據(jù)接口的設(shè)計杨帽。它的大原則容易把握漓穿，但是細節(jié)不容易做對。
本文總結(jié) RESTful 的設(shè)計細節(jié)注盈，介紹如何設(shè)計出易于理解和使用的 API晃危。
一、URL 設(shè)計
1.1 動詞 + 賓語
RESTful 的核心思想就是老客，客戶端發(fā)出的數(shù)據(jù)操作指令都是"動詞 + 賓語"的結(jié)構(gòu)僚饭。
比如，GET /articles這個命令胧砰，GET是動詞鳍鸵，/articles是賓語。動詞通常就是五種 HTTP 方法尉间，對應 CRUD 操作偿乖。
GET：讀取（Read）
POST：新建（Create）
PUT：更新（Update）
PATCH：更新（Update）哲嘲，通常是部分更新
DELETE：刪除（Delete）
根據(jù) HTTP 規(guī)范贪薪，動詞一律大寫。
1.2 動詞的覆蓋
有些客戶端只能使用GET和POST這兩種方法眠副，服務(wù)器必須接受POST模擬其他三個方法（PUT画切、PATCH、DELETE）
這時囱怕，客戶端發(fā)出的 HTTP 請求霍弹，要加上X-HTTP-Method-Override屬性，告訴服務(wù)器應該使用哪一個動詞娃弓，覆蓋POST方法典格。
POST /api/Person/4 HTTP/1.1
X-HTTP-Method-Override: PUT
復制代碼
上面代碼中，X-HTTP-Method-Override 指定本次請求的方法是PUT台丛，而不是POST钝计。
1.3 賓語必須是名詞
賓語就是 API 的 URL，是 HTTP 動詞作用的對象。它應該是名詞私恬，不能是動詞债沮。
比如，/articles這個 URL 就是正確的本鸣，而下面的 URL 不是名詞疫衩，所以都是錯誤的。
/getAllCars
/createNewCar
/deleteAllRedCars
1.4 復數(shù) URL
既然 URL 是名詞荣德，那么應該使用復數(shù)闷煤，還是單數(shù)？這沒有統(tǒng)一的規(guī)定涮瞻，但是常見的操作是讀取一個集合鲤拿。
比如GET /articles（讀取所有文章），這里明顯應該是復數(shù)署咽。
為了統(tǒng)一起見近顷，建議都使用復數(shù) URL，比如GET /articles/2要好于GET /article/2宁否。
1.5 避免多級 URL
常見的情況是窒升，資源需要多級分類，因此很容易寫出多級的 URL慕匠，比如獲取某個作者的某一類文章饱须。
GET /authors/12/categories/2復制代碼
這種 URL 不利于擴展，語義也不明確台谊，往往要想一會蓉媳，才能明白含義。
更好的做法是锅铅，除了第一級酪呻，其他級別都用查詢字符串表達。
GET /authors/12?categories=2復制代碼
下面是另一個例子狠角，查詢已發(fā)布的文章。你可能會設(shè)計成下面的 URL蚪腋。
GET /articles/published復制代碼
查詢字符串的寫法明顯更好丰歌。
GET /articles?published=true
復制代碼
二、狀態(tài)碼
2.1 狀態(tài)碼必須精確
客戶端的每一次請求屉凯，服務(wù)器都必須給出回應立帖。回應包括 HTTP 狀態(tài)碼和數(shù)據(jù)兩部分悠砚。
HTTP 狀態(tài)碼就是一個三位數(shù)晓勇，分成五個類別。
1xx：相關(guān)信息
2xx：操作成功
3xx：重定向
4xx：客戶端錯誤
5xx：服務(wù)器錯誤
這五大類總共包含100多種狀態(tài)碼，覆蓋了絕大部分可能遇到的情況绑咱。
每一種狀態(tài)碼都有標準的（或者約定的）解釋绰筛，客戶端只需查看狀態(tài)碼，就可以判斷出發(fā)生了什么情況描融，所以服務(wù)器應該返回盡可能精確的狀態(tài)碼铝噩。
API 不需要1xx狀態(tài)碼，下面介紹其他四類狀態(tài)碼的精確含義窿克。
2.2 2xx 狀態(tài)碼
200狀態(tài)碼表示操作成功骏庸，但是不同的方法可以返回更精確的狀態(tài)碼。
GET: 200 OK
POST: 201 Created
PUT: 200 OK
PATCH: 200 OK
DELETE: 204 No Content
上面代碼中年叮，POST返回201狀態(tài)碼具被，表示生成了新的資源；DELETE返回204狀態(tài)碼只损，表示資源已經(jīng)不存在一姿。
此外，202 Accepted狀態(tài)碼表示服務(wù)器已經(jīng)收到請求改执，但還未進行處理啸蜜，會在未來再處理，通常用于異步操作辈挂。
下面是一個例子衬横。
HTTP/1.1 202 Accepted
{
"task": {
"href": "/api/company/job-management/jobs/2130040",
"id": "2130040"
}
}
復制代碼
2.3 3xx 狀態(tài)碼
API 用不到301狀態(tài)碼（永久重定向）和302狀態(tài)碼（暫時重定向，307也是這個含義）
因為它們可以由應用級別返回终蒂，瀏覽器會直接跳轉(zhuǎn)蜂林，API 級別可以不考慮這兩種情況。
API 用到的3xx狀態(tài)碼拇泣，主要是303 See Other噪叙，表示參考另一個 URL。
它與302和307的含義一樣霉翔，也是"暫時重定向"睁蕾，區(qū)別在于302和307用于GET請求，而303用于POST债朵、PUT和DELETE請求子眶。
收到303以后，瀏覽器不會自動跳轉(zhuǎn)序芦，而會讓用戶自己決定下一步怎么辦臭杰。
下面是一個例子。
HTTP/1.1 303 See Other
Location: /api/orders/12345復制代碼
2.4 4xx 狀態(tài)碼
4xx狀態(tài)碼表示客戶端錯誤谚中，主要有下面幾種：
400 Bad Request：服務(wù)器不理解客戶端的請求渴杆，未做任何處理
401 Unauthorized：用戶未提供身份驗證憑據(jù)寥枝，或者沒有通過身份驗證
403 Forbidden：用戶通過了身份驗證，但是不具有訪問資源所需的權(quán)限
404 Not Found：所請求的資源不存在磁奖，或不可用
405 Method Not Allowed：用戶已經(jīng)通過身份驗證囊拜，但是所用的 HTTP 方法不在他的權(quán)限之內(nèi)
410 Gone：所請求的資源已從這個地址轉(zhuǎn)移，不再可用
415 Unsupported Media Type：客戶端要求的返回格式不支持点寥。比如艾疟，API 只能返回 JSON 格式，但是客戶端要求返回 XML 格式
422 Unprocessable Entity ：客戶端上傳的附件無法處理敢辩，導致請求失敗
429 Too Many Requests：客戶端的請求次數(shù)超過限額蔽莱。
2.5 5xx 狀態(tài)碼
5xx狀態(tài)碼表示服務(wù)端錯誤。一般來說戚长，API 不會向用戶透露服務(wù)器的詳細信息盗冷，所以只要兩個狀態(tài)碼就夠了。
500 Internal Server Error：客戶端請求有效同廉，服務(wù)器處理時發(fā)生了意外
503 Service Unavailable：服務(wù)器無法處理請求仪糖，一般用于網(wǎng)站維護狀態(tài)
三、服務(wù)器回應
3.1 不要返回純本文
API 返回的數(shù)據(jù)格式迫肖，不應該是純文本锅劝，而應該是一個 JSON 對象，因為這樣才能返回標準的結(jié)構(gòu)化數(shù)據(jù)蟆湖。
所以故爵，服務(wù)器回應的 HTTP 頭的Content-Type屬性要設(shè)為application/json。
客戶端請求時隅津，也要明確告訴服務(wù)器诬垂，可以接受 JSON 格式，即請求的 HTTP 頭的ACCEPT屬性也要設(shè)成application/json伦仍。
下面是一個例子结窘。
GET /orders/2 HTTP/1.1
Accept: application/json
復制代碼
3.2 發(fā)生錯誤時，不要返回 200 狀態(tài)碼
有一種不恰當?shù)淖龇ㄊ浅淅叮词拱l(fā)生錯誤隧枫，也返回200狀態(tài)碼，把錯誤信息放在數(shù)據(jù)體里面谓苟，就像下面這樣官脓。
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "failure",
"data": {
"error": "Expected at least two items in list."
}
}
復制代碼
上面代碼中，解析數(shù)據(jù)體以后娜谊，才能得知操作失敗确买。
這張做法實際上取消了狀態(tài)碼斤讥，這是完全不可取的纱皆。正確的做法是湾趾，狀態(tài)碼反映發(fā)生的錯誤，具體的錯誤信息放在數(shù)據(jù)體里面返回派草。
下面是一個例子搀缠。
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "Invalid payoad.",
"detail": {
"surname": "This field is required."
}
}
復制代碼
3.3 提供鏈接
API 的使用者未必知道，URL 是怎么設(shè)計的近迁。一個解決方法就是艺普，在回應中，給出相關(guān)鏈接鉴竭，便于下一步操作歧譬。
這樣的話，用戶只要記住一個 URL搏存，就可以發(fā)現(xiàn)其他的 URL瑰步。這種方法叫做 HATEOAS。
舉例來說璧眠，GitHub 的 API 都在 api.github.com 這個域名缩焦。訪問它，就可以得到其他 URL责静。
{
...
"feeds_url": "https://api.github.com/feeds",
"followers_url": "https://api.github.com/user/followers",
"following_url": "https://api.github.com/user/following{/target}",
"gists_url": "https://api.github.com/gists{/gist_id}",
"hub_url": "https://api.github.com/hub",
...
}復制代碼
上面的回應中袁滥，挑一個 URL 訪問，又可以得到別的 URL灾螃。對于用戶來說题翻，不需要記住 URL 設(shè)計，只要從 api.github.com 一步步查找就可以了睦焕。
HATEOAS 的格式?jīng)]有統(tǒng)一規(guī)定藐握，上面例子中，GitHub 將它們與其他屬性放在一起垃喊。更好的做法應該是猾普，將相關(guān)鏈接與其他屬性分開。
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "In progress",
"links": {[
{ "rel":"cancel", "method": "delete", "href":"/api/status/12345" } ,
{ "rel":"edit", "method": "put", "href":"/api/status/12345" }
]}
}復制代碼
End
作者：阮一峰
來源：
http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html
本文版權(quán)歸作者所有
