本文作者:心月

RESTful API 設計風格詳細介紹

心月IT博客 2019-04-08
摘要:RESTful一種架構風格、設計風格,而不是標準,只是提供了一組設計原則和約束條件。它主要用于客戶端和服務器的交互。REST最大的幾個特點為:資源、統一接口、URI和無狀態。

1、什么是RESTful

    RESTful一種架構風格、設計風格,而不是標準,只是提供了一組設計原則和約束條件。它主要用于客戶端和服務器的交互。

REST即Representational State Transfer的縮寫,可譯為"表現層狀態轉化”。REST最大的幾個特點為:資源、統一接口、URI和無狀態。


2、REST架構風格的特點

①資源

    所謂"資源",就是網絡上的一個實體,或者說是網絡上的一個具體信息。它可以是一段文本、一張圖片、一首歌曲、一種服務,總之就是一個具體的實在。資源總要通過某種載體反應其內容,文本可以用txt格式表現,也可以用HTML格式、XML格式表現,甚至可以采用二進制格式;圖片可以用JPG格式表現,也可以用PNG格式表現;JSON是現在最常用的資源表示格式。


②統一接口

    RESTful架構風格規定,數據的元操作,即CRUD(create, read, update和delete,即數據的增刪查改)操作,分別對應于HTTP方法:GET用來獲取資源,POST用來新建資源(也可以用于更新資源),PUT用來更新資源,DELETE用來刪除資源,這樣就統一了數據操作的接口,僅通過HTTP方法,就可以完成對數據的所有增刪查改工作。

GET(SELECT):從服務器取出資源(一項或多項)。
POST(CREATE):在服務器新建一個資源。
PUT(UPDATE):在服務器更新資源(客戶端提供完整資源數據)。
PATCH(UPDATE):在服務器更新資源(客戶端提供需要修改的資源數據)。
DELETE(DELETE):從服務器刪除資源。


③URI

    可以用一個URI(統一資源定位符)指向資源,即每個URI都對應一個特定的資源。要獲取這個資源,訪問它的URI就可以,因此URI就成了每一個資源的地址或識別符。

    一般的,每個資源至少有一個URI與之對應,最典型的URI即URL。


④無狀態

    所謂無狀態的,即所有的資源,都可以通過URI定位,而且這個定位與其他資源無關,也不會因為其他資源的變化而改變。

    有狀態和無狀態的區別,舉個簡單的例子說明一下。如查詢員工的工資,如果查詢工資是需要登錄系統,進入查詢工資的頁面,執行相關操作后,獲取工資的多少,則這種情況是有狀態的,因為查詢工資的每一步操作都依賴于前一步操作,只要前置操作不成功,后續操作就無法執行;如果輸入一個url即可得到指定員工的工資,則這種情況是無狀態的,因為獲取工資不依賴于其他資源或狀態,且這種情況下,員工工資是一個資源,由一個url與之對應,可以通過HTTP中的GET方法得到資源,這是典型的RESTful風格。


3、RESTful架構風格的實踐應用

①URI設計

a.動詞+賓語:

    RESTful 的核心思想就是,客戶端發出的數據操作指令都是"動詞 + 賓語"的結構。比如,GET /articles這個命令,GET是動詞,/articles是賓語。

動詞通常就是五種 HTTP 方法,對應 CRUD 操作:

GET:讀取(Read)
POST:新建(Create)
PUT:更新(Update)
PATCH:更新(Update),通常是部分更新
DELETE:刪除(Delete)

    根據 HTTP 規范,動詞一律大寫。


b.動詞的覆蓋:

    有些客戶端只能使用GET和POST這兩種方法。服務器必須接受POST模擬其他三個方法(PUT、PATCH、DELETE)。

    這時,客戶端發出的 HTTP 請求,要加上X-HTTP-Method-Override屬性,告訴服務器應該使用哪一個動詞,覆蓋POST方法。

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

    上面代碼中,X-HTTP-Method-Override指定本次請求的方法是PUT,而不是POST。


c.賓語必須是名詞:

    賓語就是 API 的 URL,是 HTTP 動詞作用的對象。它應該是名詞,不能是動詞。比如,/articles這個 URL 就是正確的,而下面的 URL 不是名詞,所以都是錯誤的。

/getAllCars
/createNewCar
/deleteAllRedCars


d.復數URL:

    既然 URL 是名詞,那么應該使用復數,還是單數?

    這沒有統一的規定,但是常見的操作是讀取一個集合,比如GET /articles(讀取所有文章),這里明顯應該是復數。

    為了統一起見,建議都使用復數 URL,比如GET /articles/2要好于GET /article/2。


e.避免多級URL:

    常見的情況是,資源需要多級分類,因此很容易寫出多級的 URL,比如獲取某個作者的某一類文章。

GET /authors/12/categories/2

這種 URL 不利于擴展,語義也不明確,往往要想一會,才能明白含義。

更好的做法是,除了第一級,其他級別都用查詢字符串表達。

GET /authors/12?categories=2

下面是另一個例子,查詢已發布的文章。你可能會設計成下面的 URL。

GET /articles/published

查詢字符串的寫法明顯更好。

GET /articles?published=true


②狀態碼

a.狀態碼必須精確

    客戶端的每一次請求,服務器都必須給出回應。回應包括 HTTP 狀態碼和數據兩部分。

HTTP 狀態碼就是一個三位數,分成五個類別。

1xx:相關信息
2xx:操作成功
3xx:重定向
4xx:客戶端錯誤
5xx:服務器錯誤

這五大類總共包含100多種狀態碼,覆蓋了絕大部分可能遇到的情況。每一種狀態碼都有標準的(或者約定的)解釋,客戶端只需查看狀態碼,就可以判斷出發生了什么情況,所以服務器應該返回盡可能精確的狀態碼。

API 不需要1xx狀態碼,下面介紹其他四類狀態碼的精確含義。


2XX狀態碼:

    200狀態碼表示操作成功,但是不同的方法可以返回更精確的狀態碼。

GET: 200 OK
POST: 201 Created
PUT: 200 OK
PATCH: 200 OK
DELETE: 204 No Content

    上面代碼中,POST返回201狀態碼,表示生成了新的資源;DELETE返回204狀態碼,表示資源已經不存在。

    此外,202 Accepted狀態碼表示服務器已經收到請求,但還未進行處理,會在未來再處理,通常用于異步操作。下面是一個例子。

HTTP/1.1 202 Accepted

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


3XX狀態碼:

    API 用不到301狀態碼(永久重定向)和302狀態碼(暫時重定向,307也是這個含義),因為它們可以由應用級別返回,瀏覽器會直接跳轉,API 級別可以不考慮這兩種情況。

    API 用到的3xx狀態碼,主要是303 See Other,表示參考另一個 URL。它與302和307的含義一樣,也是"暫時重定向",區別在于302和307用于GET請求,而303用于POST、PUT和DELETE請求。收到303以后,瀏覽器不會自動跳轉,而會讓用戶自己決定下一步怎么辦。下面是一個例子。

HTTP/1.1 303 See 
OtherLocation: /api/orders/12345


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:客戶端的請求次數超過限額。


5XX狀態碼:

    5xx狀態碼表示服務端錯誤。一般來說,API 不會向用戶透露服務器的詳細信息,所以只要兩個狀態碼就夠了。

500 Internal Server Error:客戶端請求有效,服務器處理時發生了意外。
503 Service Unavailable:服務器無法處理請求,一般用于網站維護狀態。


③服務器回應:

a.不要返回純文本

    API 返回的數據格式,不應該是純文本,而應該是一個 JSON 對象,因為這樣才能返回標準的結構化數據。所以,服務器回應的 HTTP 頭的Content-Type屬性要設為application/json。

    客戶端請求時,也要明確告訴服務器,可以接受 JSON 格式,即請求的 HTTP 頭的ACCEPT屬性也要設成application/json。下面是一個例子。

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


b.發生錯誤時不要返回200狀態碼

    有一種不恰當的做法是,即使發生錯誤,也返回200狀態碼,把錯誤信息放在數據體里面,就像下面這樣。

HTTP/1.1 200 OKContent-Type: application/json{
  "status": "failure",
  "data": {
    "error": "Expected at least two items in list."
  }}

    上面代碼中,解析數據體以后,才能得知操作失敗。

    這種做法實際上取消了狀態碼,這是完全不可取的。正確的做法是,狀態碼反映發生的錯誤,具體的錯誤信息放在數據體里面返回。下面是一個例子。

HTTP/1.1 400 Bad RequestContent-Type: application/json{
  "error": "Invalid payoad.",
  "detail": {
     "surname": "This field is required."
  }}


c.提供鏈接

    API 的使用者未必知道,URL 是怎么設計的。一個解決方法就是,在回應中,給出相關鏈接,便于下一步操作。這樣的話,用戶只要記住一個 URL,就可以發現其他的 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 設計,只要從 api.github.com 一步步查找就可以了。

    HATEOAS 的格式沒有統一規定,上面例子中,GitHub 將它們與其他屬性放在一起。更好的做法應該是,將相關鏈接與其他屬性分開。

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


文章版權及轉載聲明:

作者:心月 本文地址:http://www.rawkpk.live/other/229.html發布于 2019-07-01
文章轉載或復制請以超鏈接形式并注明出處心月IT博客

分享到:
贊(

發表評論

快捷輸入:

    評論列表 (有 0 條評論,人圍觀)參與討論