Restful API設計規範

2021-09-24 21:12:33 字數 1295 閱讀 3840

restful與技術無關,他是一種軟體架構的風格, rest是representational state transfer,中文翻譯為表徵狀態轉移。restful是以資源的角度來審視整個網路,將分布在網路各個節點的資源通過url進行標識,客戶端通近url來獲取資源的表徵,獲取表徵之後加上相應的動詞(put/delete/post/get/patch)來改變資源的表徵狀態。將一切資料都視為資源是rest區別其他架構風格最本質的屬性。

rfc 3986定義了通用的語法:

uri=scheme"://"authority"@"host":"ip"/"path["?"query]["#"fragment]

scheme:使用的協議,如http https ftp

host:伺服器的ip位址或者網域名稱

port:埠

path:訪問資源的路徑,就是各種web框架中定義的route路由

query:傳送給伺服器的引數

fragment:錨點,定義到頁面的資源,錨點為資源id

restful的核心思想就是客戶端發出的資料操作指令是「動詞+賓語」的結構,如 get /articles這個命令 get是動詞 /articles是賓語。

動詞通常就是http的五種方法,對應crud操作

有些客戶端只能使用get和post兩種http方法。可以使用post方法來模擬(put/patch/delete)這三個方法。這時客戶端的http請求要加上x-http-method-override屬性,告訴服務端來使用哪乙個動詞覆蓋當前的post方法,如下例如下:

post /api/articles/

x-http-method-override: delete

賓語就是是api的url部分,是http動詞作用的物件。它應該是名詞而不能是動詞

為了統一,建議使用複數url

資源需要多級分類,很容易寫出多級url,但是這種url不利於擴充套件,語義也不明確,建議除了第一級,其他級別都用查詢字串表示。如下面兩個url的比較

get /api/authors/1/articles/10 

get /api/authors/1?articles=10

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

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

這五類包含了100多種狀態碼,覆蓋了大部分可能遇到的情況,每一種狀態碼都有標準或約定的解釋,客戶端可以根據狀態碼就知道發生了什麼情況,所以服務端已應該盡可能返回精確的狀態碼

狀態碼詳情請參考這裡

參考  《《

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 是目前最流行的 api 設計規範,用於 web 資料介面的設計。它的大原則容易把握,但是細節不容易做對。本文總結 restful 的設計細節,介紹如何設計出易於理解和使用的 api。restful的核心思想就是,客戶端發出的資料 操作指令都是 動詞 賓語 的結構,比如get arti...