RESTful API設計規範

2022-05-13 01:51:11 字數 4559 閱讀 4645

**:

restful 是目前最流行的 api 設計規範,用於 web 資料介面的設計。

它的大原則容易把握,但是細節不容易做對。本文總結 restful 的設計細節,介紹如何設計出易於理解和使用的 api。

restful的核心思想就是,客戶端發出的資料+操作指令都是「動詞+賓語」的結構,比如get

/articles這個命令,get是動詞,/articles是賓語,動詞通常就有5種http請求方法,對應crud操作,根據 http 規範,動詞一律大寫。

# get:讀取(read)

# post:新建(create)

# put:更新(update)

# patch:更新(update),通常是部分更新

# delete:刪除(delete)

有些客戶端只能使用getpost這兩種方法。伺服器必須接受post模擬其他三個方法(putpatchdelete)。這時,客戶端發出的 http 請求,要加上x-http-method-override

屬性,告訴伺服器應該使用哪乙個動詞,覆蓋post方法。

上面**中,x-http-method-override指定本次請求的方法是put,而不是post

賓語就是 api 的 url,是 http 動詞作用的物件。它應該是名詞,不能是動詞。比如,/articles這個 url 就是正確的,而下面的

url 不是名詞,所以都是錯誤的。

# /getallcars

# /createnewcar

# /deleteallredcars

既然 url 是名詞,那麼應該使用複數,還是單數?這沒有統一的規定,但是常見的操作是讀取乙個集合,比如get /articles

(讀取所有文章),這裡明顯應該是複數。

為了統一起見,建議都使用複數 url,比如get /articles/2要好於get /article/2

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

# get /authors/12/categories/2

這種 url 不利於擴充套件,語義也不明確,往往要想一會,才能明白含義。

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

# get /authors/12?categories=2

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

# get /articles/published

查詢字串的寫法明顯更好

# get /articles?published=true

客戶端的每一次請求,伺服器都必須給出回應。回應包括 http 狀態碼和資料兩部分。

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

# 1xx:相關資訊

# 2xx:操作成功

# 3xx:重定向

# 4xx:客戶端錯誤

# 5xx:伺服器錯誤

這五大類總共包含  100多種

狀態碼,覆蓋了絕大部分可能遇到的情況。每一種狀態碼都有標準的(或者約定的)解釋,客戶端只需檢視狀態碼,就可以判斷出發生了什麼情況,所以伺服器應該返回盡可能精確的狀態碼。

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

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

# get: 200

ok # post:

201created

# put:

200ok

# patch:

200ok

# delete:

204 no content

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

此外,202 accepted狀態碼表示伺服器已經收到請求,但還未進行處理,會在未來再處理,通常用於非同步操作。下面是乙個例子。

api 用不到301狀態碼(永久重定向)和302狀態碼(暫時重定向,307

也是這個含義),因為它們可以由應用級別返回,瀏覽器會直接跳轉,api 級別可以不考慮這兩種情況。

api 用到的3xx狀態碼,主要是303 see other,表示參考另乙個 url。它與302307

的含義一樣,也是"暫時重定向",區別在於302307用於get請求,而303用於postputdelete請求。收到303以後,瀏覽器不會自動跳轉,而會讓使用者自己決定下一步怎麼辦。下面是乙個例子。

4xx狀態碼表示客戶端錯誤,主要有下面幾種。

400 bad request:伺服器不理解客戶端的請求,未做任何處理。

401 unauthorized:使用者未提供身份驗證憑據,或者沒有通過身份驗證。

403 forbidden:使用者通過了身份驗證,但是不具有訪問資源所需的許可權。

404 not found:所請求的資源不存在,或不可用。

405 method not allowed:使用者已經通過身份驗證,但是所用的 http 方法不在他的許可權之內。

415 unsupported media type:客戶端要求的返回格式不支援。比如,api 只能返回 json 格式,但是客戶端要求返回

xml 格式。

422 unprocessable entity:客戶端上傳的附件無法處理,導致請求失敗。

429 too many requests:客戶端的請求次數超過限額。

5xx狀態碼表示服務端錯誤。一般來說,api 不會向使用者透露伺服器的詳細資訊,所以只要兩個狀態碼就夠了。

500 internal server error:客戶端請求有效,伺服器處理時發生了意外。

發生錯誤時,不要返回 200

狀態碼有一種不恰當的做法是,即使發生錯誤,也返回

200 狀態碼,把錯誤資訊放在資料體裡面,就像下面這樣。

上面**中,解析資料體以後,才能得知操作失敗。

這張做法實際上取消了狀態碼,這是完全不可取的。正確的做法是,狀態碼反映發生的錯誤,具體的錯誤資訊放在資料體裡面返回。下面是乙個例子。

api 的使用者未必知道,url 是怎麼設計的。乙個解決方法就是,在回應中,給出相關鏈結,便於下一步操作。這樣的話,使用者只要記住乙個

url,就可以發現其他的 url。這種方法叫做 hateoas。

舉例來說,github 的 api 都在  api.github.com

這個網域名稱。訪問它,就可以得到其他 url。

",

"gists_url

": "

","hub_url

": "

",...

}

上面的回應中,挑乙個 url 訪問,又可以得到別的 url。對於使用者來說,不需要記住 url 設計,只要從 api.github.com

一步步查詢就可以了。

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

restful api 設計規範

1.同一種資料的操作,只設定乙個url路由,也就是根據請求方法的不同來區分處理邏輯。可以基於fbv來通過請求方法的不同,處理不同的邏輯,也可以基於cbv來實現。兩種方式cbv更加簡潔,不需要判斷 2.網域名稱 為了對使用者使用的url和網頁中使用的介面api進行區別,1 子網域名稱的方式區分,例如 ...

RESTful API 設計規範

restful 是目前最流行的 api 設計規範,用於 web 資料介面的設計。1.1 動詞 賓語 restful 的核心思想就是,客戶端發出的資料操作指令都是 動詞 賓語 的結構。比如,get articles這個命令,get是動詞,articles是賓語。動詞通常就是五種 http 方法,對應 ...

Restful API設計規範

restful與技術無關,他是一種軟體架構的風格,rest是representational state transfer,中文翻譯為表徵狀態轉移。restful是以資源的角度來審視整個網路,將分布在網路各個節點的資源通過url進行標識,客戶端通近url來獲取資源的表徵,獲取表徵之後加上相應的動詞 ...