RESTful API設(shè)計(jì)規(guī)范，看這篇就夠了！

RESTful 是目前最流行的 API 設(shè)計(jì)規(guī)范，用于 Web 數(shù)據(jù)接口的設(shè)計(jì)。

它的大原則容易把握，但是細(xì)節(jié)不容易做對(duì)。本文總結(jié) RESTful 的設(shè)計(jì)細(xì)節(jié)，介紹如何設(shè)計(jì)出易于理解和使用的 API。

一 URL設(shè)計(jì)

動(dòng)詞+賓語(yǔ)

RESTful的核心思想就是，客戶端發(fā)出的數(shù)據(jù)+操作指令都是“動(dòng)詞+賓語(yǔ)”的結(jié)構(gòu)，比如GET /articles這個(gè)命令，GET是動(dòng)詞，/articles是賓語(yǔ)，動(dòng)詞通常就有5種HTTP請(qǐng)求方法，對(duì)應(yīng)CRUD操作，根據(jù) HTTP 規(guī)范，動(dòng)詞一律大寫(xiě)。關(guān)注公眾號(hào)程序員小樂(lè)回復(fù)關(guān)鍵字“offer”獲取算法面試題和答案。

# GET：讀?。≧ead）
# POST：新建（Create）
# PUT：更新（Update）
# PATCH：更新（Update），通常是部分更新
# DELETE：刪除（Delete）

動(dòng)詞的覆蓋

有些客戶端只能使用GET和POST這兩種方法。服務(wù)器必須接受POST模擬其他三個(gè)方法（PUT、PATCH、DELETE）。這時(shí)，客戶端發(fā)出的 HTTP 請(qǐng)求，要加上X-HTTP-Method-Override屬性，告訴服務(wù)器應(yīng)該使用哪一個(gè)動(dòng)詞，覆蓋POST方法。

POST?/api/Person/4?HTTP/1.1??
X-HTTP-Method-Override:?PUT

上面代碼中，X-HTTP-Method-Override指定本次請(qǐng)求的方法是PUT，而不是POST。

賓語(yǔ)必須是名詞

賓語(yǔ)就是 API 的 URL，是 HTTP 動(dòng)詞作用的對(duì)象。它應(yīng)該是名詞，不能是動(dòng)詞。比如，/articles這個(gè) URL 就是正確的，而下面的 URL 不是名詞，所以都是錯(cuò)誤的。

#?/getAllCars
#?/createNewCar
#?/deleteAllRedCars

復(fù)數(shù) URL

既然 URL 是名詞，那么應(yīng)該使用復(fù)數(shù)，還是單數(shù)？這沒(méi)有統(tǒng)一的規(guī)定，但是常見(jiàn)的操作是讀取一個(gè)集合，比如GET /articles（讀取所有文章），這里明顯應(yīng)該是復(fù)數(shù)。

為了統(tǒng)一起見(jiàn)，建議都使用復(fù)數(shù) URL，比如GET /articles/2要好于GET /article/2。

避免多級(jí) URL

常見(jiàn)的情況是，資源需要多級(jí)分類，因此很容易寫(xiě)出多級(jí)的 URL，比如獲取某個(gè)作者的某一類文章。關(guān)注公眾號(hào)程序員小樂(lè)回復(fù)關(guān)鍵字“Java”獲取Java面試題和答案。

#?GET?/authors/12/categories/2

這種 URL 不利于擴(kuò)展，語(yǔ)義也不明確，往往要想一會(huì)，才能明白含義。

更好的做法是，除了第一級(jí)，其他級(jí)別都用查詢字符串表達(dá)。

#?GET?/authors/12?categories=2

下面是另一個(gè)例子，查詢已發(fā)布的文章。你可能會(huì)設(shè)計(jì)成下面的 URL。

#?GET?/articles/published

查詢字符串的寫(xiě)法明顯更好

#?GET?/articles?published=true

二、狀態(tài)碼

狀態(tài)碼必須精確

客戶端的每一次請(qǐng)求，服務(wù)器都必須給出回應(yīng)?；貞?yīng)包括 HTTP 狀態(tài)碼和數(shù)據(jù)兩部分。

HTTP 狀態(tài)碼就是一個(gè)三位數(shù)，分成五個(gè)類別。

# 1xx：相關(guān)信息
# 2xx：操作成功
# 3xx：重定向
# 4xx：客戶端錯(cuò)誤
# 5xx：服務(wù)器錯(cuò)誤

這五大類總共包含100多種狀態(tài)碼，覆蓋了絕大部分可能遇到的情況。每一種狀態(tài)碼都有標(biāo)準(zhǔn)的（或者約定的）解釋，客戶端只需查看狀態(tài)碼，就可以判斷出發(fā)生了什么情況，所以服務(wù)器應(yīng)該返回盡可能精確的狀態(tài)碼。

API 不需要1xx狀態(tài)碼，下面介紹其他四類狀態(tài)碼的精確含義。

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)收到請(qǐng)求，但還未進(jìn)行處理，會(huì)在未來(lái)再處理，通常用于異步操作。下面是一個(gè)例子。

HTTP/1.1?202?Accepted

{
??"task":?{
????"href":?"/api/company/job-management/jobs/2130040",
????"id":?"2130040"
??}
}

3xx 狀態(tài)碼

API 用不到301狀態(tài)碼（永久重定向）和302狀態(tài)碼（暫時(shí)重定向，307也是這個(gè)含義），因?yàn)樗鼈兛梢杂蓱?yīng)用級(jí)別返回，瀏覽器會(huì)直接跳轉(zhuǎn)，API 級(jí)別可以不考慮這兩種情況。

API 用到的3xx狀態(tài)碼，主要是303 See Other，表示參考另一個(gè) URL。它與302和307的含義一樣，也是"暫時(shí)重定向"，區(qū)別在于302和307用于GET請(qǐng)求，而303用于POST、PUT和DELETE請(qǐng)求。收到303以后，瀏覽器不會(huì)自動(dòng)跳轉(zhuǎn)，而會(huì)讓用戶自己決定下一步怎么辦。

下面是一個(gè)例子。

HTTP/1.1?303?See?Other
Location:?/api/orders/12345

4xx 狀態(tài)碼

4xx狀態(tài)碼表示客戶端錯(cuò)誤，主要有下面幾種。

• 400 Bad Request：服務(wù)器不理解客戶端的請(qǐng)求，未做任何處理。

• 401 Unauthorized：用戶未提供身份驗(yàn)證憑據(jù)，或者沒(méi)有通過(guò)身份驗(yàn)證。

• 403 Forbidden：用戶通過(guò)了身份驗(yàn)證，但是不具有訪問(wèn)資源所需的權(quán)限。

• 404 Not Found：所請(qǐng)求的資源不存在，或不可用。

• 405 Method Not Allowed：用戶已經(jīng)通過(guò)身份驗(yàn)證，但是所用的 HTTP 方法不在他的權(quán)限之內(nèi)。

• 410 Gone：所請(qǐng)求的資源已從這個(gè)地址轉(zhuǎn)移，不再可用。

• 415 Unsupported Media Type：客戶端要求的返回格式不支持。比如，API 只能返回 JSON 格式，但是客戶端要求返回 XML 格式。

• 422 Unprocessable Entity ：客戶端上傳的附件無(wú)法處理，導(dǎo)致請(qǐng)求失敗。

• 429 Too Many Requests：客戶端的請(qǐng)求次數(shù)超過(guò)限額。

5xx 狀態(tài)碼

5xx狀態(tài)碼表示服務(wù)端錯(cuò)誤。一般來(lái)說(shuō)，API 不會(huì)向用戶透露服務(wù)器的詳細(xì)信息，所以只要兩個(gè)狀態(tài)碼就夠了。

• 500 Internal Server Error：客戶端請(qǐng)求有效，服務(wù)器處理時(shí)發(fā)生了意外。

• 503 Service Unavailable：服務(wù)器無(wú)法處理請(qǐng)求，一般用于網(wǎng)站維護(hù)狀態(tài)。

三、服務(wù)器回應(yīng)

不要返回純本文

API 返回的數(shù)據(jù)格式，不應(yīng)該是純文本，而應(yīng)該是一個(gè) JSON 對(duì)象，因?yàn)檫@樣才能返回標(biāo)準(zhǔn)的結(jié)構(gòu)化數(shù)據(jù)。所以，服務(wù)器回應(yīng)的 HTTP 頭的Content-Type屬性要設(shè)為application/json。

客戶端請(qǐng)求時(shí)，也要明確告訴服務(wù)器，可以接受 JSON 格式，即請(qǐng)求的 HTTP 頭的ACCEPT屬性也要設(shè)成application/json。下面是一個(gè)例子。

GET?/orders/2?HTTP/1.1?
Accept:?application/json

發(fā)生錯(cuò)誤時(shí)，不要返回 200 狀態(tài)碼

有一種不恰當(dāng)?shù)淖龇ㄊ?，即使發(fā)生錯(cuò)誤，也返回200狀態(tài)碼，把錯(cuò)誤信息放在數(shù)據(jù)體里面，就像下面這樣。

HTTP/1.1?200?OK
Content-Type:?application/json

{
??"status":?"failure",
??"data":?{
????"error":?"Expected?at?least?two?items?in?list."
??}
}

上面代碼中，解析數(shù)據(jù)體以后，才能得知操作失敗。

這張做法實(shí)際上取消了狀態(tài)碼，這是完全不可取的。正確的做法是，狀態(tài)碼反映發(fā)生的錯(cuò)誤，具體的錯(cuò)誤信息放在數(shù)據(jù)體里面返回。下面是一個(gè)例子。

HTTP/1.1?400?Bad?Request
Content-Type:?application/json

{
??"error":?"Invalid?payoad.",
??"detail":?{
?????"surname":?"This?field?is?required."
??}
}

提供鏈接

API 的使用者未必知道，URL 是怎么設(shè)計(jì)的。一個(gè)解決方法就是，在回應(yīng)中，給出相關(guān)鏈接，便于下一步操作。這樣的話，用戶只要記住一個(gè) URL，就可以發(fā)現(xiàn)其他的 URL。這種方法叫做 HATEOAS。

舉例來(lái)說(shuō)，GitHub 的 API 都在 api.github.com 這個(gè)域名。訪問(wèn)它，就可以得到其他 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",
??...
}

上面的回應(yīng)中，挑一個(gè) URL 訪問(wèn)，又可以得到別的 URL。對(duì)于用戶來(lái)說(shuō)，不需要記住 URL 設(shè)計(jì)，只要從 api.github.com 一步步查找就可以了。

HATEOAS 的格式?jīng)]有統(tǒng)一規(guī)定，上面例子中，GitHub 將它們與其他屬性放在一起。更好的做法應(yīng)該是，將相關(guān)鏈接與其他屬性分開(kāi)。

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"?}
??]}
}

四、參考鏈接

https://blog.florimondmanca.com/restful-api-design-13-best-practices-to-make-your-users-happy
https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design