前後端分離後,RESTful API 最佳實踐
RESTful 是目前最流行的 API 設計規範,用於 Web 數據接口的設計。
一、URL 設計
1.1 動詞 + 賓語
RESTful 的核心思想就是,客戶端發出的數據操作指令都是 "動詞 + 賓語" 的結構。比如,GET /articles
這個命令,GET
是動詞,/articles
是賓語。
動詞通常就是五種 HTTP 方法,對應 CRUD 操作。
GET:讀取(Read)
POST:新建(Create)
PUT:更新(Update)
PATCH:更新(Update),通常是部分更新
DELETE:刪除(Delete)
根據 HTTP 規範,動詞一律大寫。
1.2 動詞的覆蓋
有些客戶端只能使用GET
和POST
這兩種方法。服務器必須接受POST
模擬其他三個方法(PUT
、PATCH
、DELETE
)。
這時,客戶端發出的 HTTP 請求,要加上X-HTTP-Method-Override
屬性,告訴服務器應該使用哪一個動詞,覆蓋POST
方法。
1POST /api/Person/4 HTTP/1.1 2X-HTTP-Method-Override: PUT 3 4
上面代碼中,X-HTTP-Method-Override
指定本次請求的方法是PUT
,而不是POST
。
1.3 賓語必須是名詞
賓語就是 API 的 URL,是 HTTP 動詞作用的對象。它應該是名詞,不能是動詞。比如,/articles
這個 URL 就是正確的,而下面的 URL 不是名詞,所以都是錯誤的。
/getAllCars
/createNewCar
/deleteAllRedCars
1.4 複數 URL
既然 URL 是名詞,那麼應該使用複數,還是單數?
這沒有統一的規定,但是常見的操作是讀取一個集合,比如GET /articles
(讀取所有文章),這裏明顯應該是複數。
爲了統一起見,建議都使用複數 URL,比如GET /articles/2
要好於GET /article/2
。
1.5 避免多級 URL
常見的情況是,資源需要多級分類,因此很容易寫出多級的 URL,比如獲取某個作者的某一類文章。
1GET /authors/12/categories/2 2 3
這種 URL 不利於擴展,語義也不明確,往往要想一會,才能明白含義。
更好的做法是,除了第一級,其他級別都用查詢字符串表達。
1GET /authors/12?categories=2 2 3
下面是另一個例子,查詢已發佈的文章。你可能會設計成下面的 URL。
1GET /articles/published 2 3
查詢字符串的寫法明顯更好。
1GET /articles?published=true 2 3
二、狀態碼
2.1 狀態碼必須精確
客戶端的每一次請求,服務器都必須給出迴應。迴應包括 HTTP 狀態碼和數據兩部分。
HTTP 狀態碼就是一個三位數,分成五個類別。
1xx
:相關信息
2xx
:操作成功
3xx
:重定向
4xx
:客戶端錯誤
5xx
:服務器錯誤
這五大類總共包含 100 多種狀態碼,覆蓋了絕大部分可能遇到的情況。每一種狀態碼都有標準的(或者約定的)解釋,客戶端只需查看狀態碼,就可以判斷出發生了什麼情況,所以服務器應該返回儘可能精確的狀態碼。
API 不需要1xx
狀態碼,下面介紹其他四類狀態碼的精確含義。
2.2 2xx 狀態碼
200
狀態碼錶示操作成功,但是不同的方法可以返回更精確的狀態碼。
GET: 200 OK
POST: 201 Created
PUT: 200 OK
PATCH: 200 OK
DELETE: 204 No Content
上面代碼中,POST
返回201
狀態碼,表示生成了新的資源;DELETE
返回204
狀態碼,表示資源已經不存在。
此外,202 Accepted
狀態碼錶示服務器已經收到請求,但還未進行處理,會在未來再處理,通常用於異步操作。下面是一個例子。
1HTTP/1.1 202 Accepted 2 3{ 4 "task": { 5 "href": "/api/company/job-management/jobs/2130040", 6 "id": "2130040" 7 } 8} 9 10
2.3 3xx 狀態碼
API 用不到301
狀態碼(永久重定向)和302
狀態碼(暫時重定向,307
也是這個含義),因爲它們可以由應用級別返回,瀏覽器會直接跳轉,API 級別可以不考慮這兩種情況。
API 用到的3xx
狀態碼,主要是303 See Other
,表示參考另一個 URL。它與302
和307
的含義一樣,也是 "暫時重定向",區別在於302
和307
用於GET
請求,而303
用於POST
、PUT
和DELETE
請求。收到303
以後,瀏覽器不會自動跳轉,而會讓用戶自己決定下一步怎麼辦。下面是一個例子。
1HTTP/1.1 303 See Other 2Location: /api/orders/12345 3 4
2.4 4xx 狀態碼
4xx
狀態碼錶示客戶端錯誤,主要有下面幾種。
400 Bad Request
:服務器不理解客戶端的請求,未做任何處理。
401 Unauthorized
:用戶未提供身份驗證憑據,或者沒有通過身份驗證。
403 Forbidden
:用戶通過了身份驗證,但是不具有訪問資源所需的權限。
404 Not Found
:所請求的資源不存在,或不可用。
405 Method Not Allowed
:用戶已經通過身份驗證,但是所用的 HTTP 方法不在他的權限之內。
410 Gone
:所請求的資源已從這個地址轉移,不再可用。
415 Unsupported Media Type
:客戶端要求的返回格式不支持。比如,API 只能返回 JSON 格式,但是客戶端要求返回 XML 格式。
422 Unprocessable Entity
:客戶端上傳的附件無法處理,導致請求失敗。
429 Too Many Requests
:客戶端的請求次數超過限額。
2.5 5xx 狀態碼
5xx
狀態碼錶示服務端錯誤。一般來說,API 不會向用戶透露服務器的詳細信息,所以只要兩個狀態碼就夠了。
500 Internal Server Error
:客戶端請求有效,服務器處理時發生了意外。
503 Service Unavailable
:服務器無法處理請求,一般用於網站維護狀態。
三、服務器迴應
3.1 不要返回純本文
API 返回的數據格式,不應該是純文本,而應該是一個 JSON 對象,因爲這樣才能返回標準的結構化數據。所以,服務器迴應的 HTTP 頭的Content-Type
屬性要設爲application/json
。
客戶端請求時,也要明確告訴服務器,可以接受 JSON 格式,即請求的 HTTP 頭的ACCEPT
屬性也要設成application/json
。下面是一個例子。
1GET /orders/2 HTTP/1.1 2Accept: application/json 3 4
3.2 發生錯誤時,不要返回 200 狀態碼
有一種不恰當的做法是,即使發生錯誤,也返回200
狀態碼,把錯誤信息放在數據體裏面,就像下面這樣。
1HTTP/1.1 200 OK 2Content-Type: application/json 3 4{ 5 "status": "failure", 6 "data": { 7 "error": "Expected at least two items in list." 8 } 9} 10 11
上面代碼中,解析數據體以後,才能得知操作失敗。
這張做法實際上取消了狀態碼,這是完全不可取的。正確的做法是,狀態碼反映發生的錯誤,具體的錯誤信息放在數據體裏面返回。下面是一個例子。
1HTTP/1.1 400 Bad Request 2Content-Type: application/json 3 4{ 5 "error": "Invalid payoad.", 6 "detail": { 7 "surname": "This field is required." 8 } 9} 10 11
3.3 提供鏈接
API 的使用者未必知道,URL 是怎麼設計的。一個解決方法就是,在迴應中,給出相關鏈接,便於下一步操作。這樣的話,用戶只要記住一個 URL,就可以發現其他的 URL。這種方法叫做 HATEOAS。
舉例來說,GitHub 的 API 都在 api.github.com 這個域名。訪問它,就可以得到其他 URL。
1{ 2 ... 3 "feeds_url": "https://api.github.com/feeds", 4 "followers_url": "https://api.github.com/user/followers", 5 "following_url": "https://api.github.com/user/following{/target}", 6 "gists_url": "https://api.github.com/gists{/gist_id}", 7 "hub_url": "https://api.github.com/hub", 8 ... 9} 10 11
上面的迴應中,挑一個 URL 訪問,又可以得到別的 URL。對於用戶來說,不需要記住 URL 設計,只要從 api.github.com 一步步查找就可以了。
HATEOAS 的格式沒有統一規定,上面例子中,GitHub 將它們與其他屬性放在一起。更好的做法應該是,將相關鏈接與其他屬性分開。
1HTTP/1.1 200 OK 2Content-Type: application/json 3 4{ 5 "status": "In progress", 6 "links": {[ 7 { "rel":"cancel", "method": "delete", "href":"/api/status/12345" } , 8 { "rel":"edit", "method": "put", "href":"/api/status/12345" } 9 ]} 10} 11 12
本文由 Readfog 進行 AMP 轉碼,版權歸原作者所有。
來源:https://mp.weixin.qq.com/s/8lg33Vdb_dif5N_Ue9jHHA