簡潔 RESTful API 設(shè)計規(guī)范!整個人都清爽了!
RESTful 是目前最流行的 API 設(shè)計規(guī)范,用于 Web 數(shù)據(jù)接口的設(shè)計。它的大原則容易把握,但是細節(jié)不容易做對。本文總結(jié) RESTful 的設(shè)計細節(jié),介紹如何設(shè)計出易于理解和使用的 API。
URL設(shè)計
動詞+賓語
# GET:讀?。≧ead)# POST:新建(Create)# PUT:更新(Update)# PATCH:更新(Update),通常是部分更新# DELETE:刪除(Delete)
動詞的覆蓋
GET和POST這兩種方法。服務(wù)器必須接受POST模擬其他三個方法(PUT、PATCH、DELETE)。這時,客戶端發(fā)出的 HTTP 請求,要加上X-HTTP-Method-Override屬性,告訴服務(wù)器應(yīng)該使用哪一個動詞,覆蓋POST方法。
POST /api/Person/4 HTTP/1.1X-HTTP-Method-Override: PUT
上面代碼中,X-HTTP-Method-Override指定本次請求的方法是PUT,而不是POST。
賓語必須是名詞
/articles這個 URL 就是正確的,而下面的 URL 不是名詞,所以都是錯誤的。
# /getAllCars# /createNewCar# /deleteAllRedCars
復(fù)數(shù) URL
GET /articles(讀取所有文章),這里明顯應(yīng)該是復(fù)數(shù)。
GET /articles/2要好于GET /article/2。
避免多級 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)碼
狀態(tài)碼必須精確
客戶端的每一次請求,服務(wù)器都必須給出回應(yīng)。回應(yīng)包括 HTTP 狀態(tài)碼和數(shù)據(jù)兩部分。
HTTP 狀態(tài)碼就是一個三位數(shù),分成五個類別。
# 1xx:相關(guān)信息# 2xx:操作成功# 3xx:重定向# 4xx:客戶端錯誤# 5xx:服務(wù)器錯誤
這五大類總共包含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)收到請求,但還未進行處理,會在未來再處理,通常用于異步操作。下面是一個例子。
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)碼(暫時重定向,307也是這個含義),因為它們可以由應(yīng)用級別返回,瀏覽器會直接跳轉(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 OtherLocation: /api/orders/12345
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 :客戶端上傳的附件無法處理,導(dǎo)致請求失敗。
429 Too Many Requests:客戶端的請求次數(shù)超過限額。
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ù)器回應(yīng)
不要返回純本文
API 返回的數(shù)據(jù)格式,不應(yīng)該是純文本,而應(yīng)該是一個 JSON 對象,因為這樣才能返回標(biāo)準(zhǔn)的結(jié)構(gòu)化數(shù)據(jù)。所以,服務(wù)器回應(yīng)的 HTTP 頭的Content-Type屬性要設(shè)為application/json。
客戶端請求時,也要明確告訴服務(wù)器,可以接受 JSON 格式,即請求的 HTTP 頭的ACCEPT屬性也要設(shè)成application/json。下面是一個例子。
GET /orders/2 HTTP/1.1Accept: application/json
發(fā)生錯誤時,不要返回 200 狀態(tài)碼
有一種不恰當(dāng)?shù)淖龇ㄊ?,即使發(fā)生錯誤,也返回200狀態(tài)碼,把錯誤信息放在數(shù)據(jù)體里面,就像下面這樣。
HTTP/1.1 200 OKContent-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 RequestContent-Type: application/json{"error": "Invalid payoad.","detail": {"surname": "This field is required."}}
提供鏈接
API 的使用者未必知道,URL 是怎么設(shè)計的。一個解決方法就是,在回應(yīng)中,給出相關(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",...}
上面的回應(yīng)中,挑一個 URL 訪問,又可以得到別的 URL。對于用戶來說,不需要記住 URL 設(shè)計,只要從 api.github.com 一步步查找就可以了。
HATEOAS 的格式?jīng)]有統(tǒng)一規(guī)定,上面例子中,GitHub 將它們與其他屬性放在一起。更好的做法應(yīng)該是,將相關(guān)鏈接與其他屬性分開。
HTTP/1.1 200 OKContent-Type: application/json{"status": "In progress","links": {[{ "rel":"cancel", "method": "delete", "href":"/api/status/12345" } ,{ "rel":"edit", "method": "put", "href":"/api/status/12345" }]}}
參考鏈接
RESTful API Design: 13 Best Practices to Make Your Users Happy, by Florimond Manca
API design, by MicroSoft Azure
作者:馬一特
鏈接:cnblogs.com/mayite/p/9798913.html

掃描下方二維碼回復(fù):數(shù)據(jù)結(jié)構(gòu),
可獲取下載鏈接
???
?長按上方二維碼 2 秒
回復(fù)「數(shù)據(jù)結(jié)構(gòu)」即可獲取資料
點贊是最大的支持 
