RESTful架構與RESTful API設計

2021-08-20 07:43:53 字數 3296 閱讀 1685

rest這個詞是roy thomas fielding博士在他2023年的博士**中提出的,fielding將他對網際網路軟體的架構原則定名為rest,即representational state transfer的縮寫,翻譯為「表現層狀態轉化」。如果乙個架構符合rest原則,就稱它為restful架構,即rest風格的架構。

rest是一種架構風格,而不是一種架構。要理解restful架構,最好的方法就是去理解representational state transfer這個詞到底是什麼意思,他的每乙個詞代表什麼含義。如果你把這個名詞搞懂了,就不難體會rest是一種什麼樣的設計。

rest的名稱「表現層狀態轉化」中省略了主語。「表現層」其實是指的「資源(resources)」的「表現層」。

所謂「資源」,就是網路上的乙個實體,或者是網路上的乙個具體資訊。它可以是一段文字、一張、一首歌曲、一種服務、總之就是乙個具體的實體。你可以用乙個uri(統一資源識別符號)指向它,每種資源對應乙個特定的url。要獲取這個資源,訪問它的uri就可以,因此uri就成了每乙個資源的位址或獨一無二的識別符。

「資源」是一種資訊實體,他可以有多種的外在表現形式。我們把「資源」具體呈現出來的形式稱之為「表現層」。比如:文字可以用txt格式表現,也可以用html格式、xml格式、json格式表現,甚至可以採用二進位制格式表現;可以採用jpg格式表現,也可以用png格式表現。

uri只代表資源的實體,不代表他的形式。嚴格地說,有些**最後的「.html」字尾名是不必要的,因為這個字尾名表示格式,屬於「表現層」的範疇,而uri應該只代表「資源」的位置。它的具體表現形式應該在http請求的頭資訊中用accept和content-type欄位指定,這兩個欄位才是對「表現層」的描述,不過在大部分應用中,通過字尾區分表現層就已經足夠了。

訪問乙個**,就代表了客戶端和伺服器的乙個互動過程。在這個過程中,勢必涉及資料和狀態的變化。

http協議是乙個無狀態網際網路通訊協議,這意味著所有狀態都儲存在伺服器端。因此,如果客戶端想要操作伺服器,必須通過某種手段,讓伺服器發生「狀態轉化(state transfer)」。而這種轉化是建立在表現層之上的,所以就叫做「表現層狀態轉化」。

客戶端用到的手段只能是http協議。具體的說,http協議裡有5個常用的表示操作方式的動詞:get、post、put、delete、patch。它們分別對應5種基本操作:get用來獲取資源,post用來新建資源(也可以用來更新資源),put用來更新資源,delete用來刪除資源,patch用來更新資源的部分屬性。

現在流行的各種web框架,包括spring boot都支援rest開發,rest並非是一種技術或者規範,而是一種架構風格,這種架構風格逐漸各種程式語言的web框架所支援。它包括了rest架構中如何標識資源,如何表示操作介面及操作版本,如何標識操作結果等,主要內容如下:

也有的使用「api」作為二級網域名稱:

/v1.1

將資源名稱放到url中,如果資源有層級關係,則放入層級關係:

/v1.1/user

如果使用者屬於系統管理,也可以這麼寫:

/v1.1/system/user

在rest中,http method常常對應一下含義:

在業務系統中,刪除往往並不是指的物理刪除,而是邏輯刪除,資源通常仍在資料庫中,只是狀態設定為刪除狀態。

restful api設計的一些例子

新增使用者:

post:/v1.1/system/user

查詢id為45的使用者

get:/v1.1/system/user/45

查詢所有使用者:

get:/v1.1/system/user

如果有翻頁,可以在後面增加類似offset、limit引數,比如:

get:/v1.1/system/user?offset=1&limit=20&sortby=name

更新使用者id為45的使用者:

put:/v1.1/system/user/45

刪除使用者id為45的使用者:

delete:/v1.1/system/user/45

get: /v1.1/system/user/45.json

返回id為45的使用者資訊,返回格式是json

伺服器向客戶端返回http status以表示操作是否成功,常用的如下:

1)每乙個uri代表一種資源

2)客戶端和伺服器之間傳遞這種資源的表現層

3)客戶端通過http動詞,對伺服器端資源進行操作,實現「表現層狀態轉化」。

一句話概括:uri定位資源,用http動詞(get,post,delete,detc)描述操作。

rest和webservice主要的差別就是前者是一種輕量級的架構,而後者是一種重量級架構。前者即適合終端到服務的呼叫,系統內部子系統的互相呼叫,也適合不同公司之間的系統互相呼叫,而webservice較為適合不同公司之間系統的呼叫。

注:有不明白webservice的同學請看下面的參考資料。

理解restful架構

restful api 設計指南

有關webservice的文章:

web service是什麼?

web service技術的soap實現

web services 系列教程

web api知識

到底 rest 和 soap、rpc 有何區別?

RESTful架構與RPC架構

在restful架構中,關注點在於資源,操作資源時使用標準方法檢索並操作資訊片段,在rpc架構中,關注點在於方法,呼叫方法時將像呼叫本地方法一樣呼叫伺服器的方法。rest即表述性狀態傳遞representational state transfer,是一種軟體架構風格,也可以稱作是一種設計api的模...

RESTful架構與RPC架構

在restful架構中,關注點在於資源,操作資源時使用標準方法檢索並操作資訊片段,在rpc架構中,關注點在於方法,呼叫方法時將像呼叫本地方法一樣呼叫伺服器的方法。rest即表述性狀態傳遞representational state transfer,是一種軟體架構風格,也可以稱作是一種設計api的模...

理解RESTful架構

理解restful架構 restful的精闢理解 看url就知道要什麼 看http method就知道幹什麼 看http status code就知道結果如何 rest不是 rest 這個單詞,而是幾個單詞縮寫。但即使那幾個單詞說出來,也無法理解在說什麼 不是要貶低人,是我自己也理解困難 rest描...