我的理解 RESTful Api 架構
一些常見的誤解
不要以為 RESTful Api 就是設計得像便於 SEO 的偽靜態,例如一個 Api 的 URL 類似於 http://xxx.com/blog/1 ,我們可以通過瀏覽器訪問該 URL 而讀取文章,但是這並不代表著它就是 RESTful Api 。
更不要認為 HTTP + JSON 就是 RESTful ApI 了。
REST 和 HTTP/1.1
Roy Fielding (Apache HTTP 伺服器的核心開發者,Apache 軟體基金會的合作創始人,HTTP/1.1 協議專家組的負責人)總結了一套理論框架,然後使用這套理論框架中的指導原則,來指導HTTP/1.1協議的設計方向。後來他在其的博士學位論文 Architectural Styles and the Design of Network-based Software Architectures 中更為系統、嚴謹地闡述了這套理論框架,並且使用這套理論框架推匯出了一種新的架構風格,並且為這種架構風格取了一個令人輕鬆愉快的名字 REST。
想必通過這個你已經明白了 REST 和 HTTP/1.1 的密不可分的關係了吧。HTTP/1.1 的很多特性就是 REST 的特性,比如連線的無狀態性。還有後面說的 REST 五大特性都和 HTTP/1.1 協議密不可分。
RESTful Api 與 SOAP Web API 在 URL 形式上的對比
從設計一個刪除評論的 api 說起
我們可以這樣設計成類似於:
或者其他形式的 url。
而 RESTful Api 則是:
我們對比可以發現①和②URL 中,都有del
的動作指示。
SOAP Web API採用RPC風格,它採用面向功能的架構,所以我們在設計SOAP Web API的時候首相考慮的是應高提供怎樣的功能(或者操作)。
而 RESTful Api 是面向資源的架構。是查詢、新增、修改、刪除,都該資源無關。
所以我們在③URL 中沒有看到del
的關鍵字,對比②和③最為明顯。
進一步認識 RESTful Api
我們知道 URL 全稱為“統一資源定位符(Uniform Resource Locator)”,用於描述 Web 資源所在的位置。RESTful Api 是以 HTTP 協議為強烈依託的,將類似於①和②這種以功能為主導的URL風格捨棄,還原 URL 的本質,它的宗旨就是一個 URL 就應該是一個資源,不能包含任何動作。
|
PUT
和PATCH
的功能都可以代表更新,但略有不同,PUT
大多時候表示更新該資源的全部資訊,而PATCH
則更新部分資訊。
PUT
和POST
又一些功能的重疊,都可以是新建一個資源,POST
時,新建資源的地址是由伺服器返回給客戶端的。也就是說客戶端在傳送POST
請求資源之前還無法預知該資源的地址,這在我們的
Api 開發中非常常見,新建一個帖子,新建一條評論,都如此。
而資源的地址是客戶端預先知道的情況則比較少。也有人如此設計而使用PUT
,比如需要對 github 上的某人的專案 star ,則可能會設計成:http://github.com/xxx/zhoumengkang/projectname/star 這裡把“對這個專案已經點贊過”看成了一個資源,那麼就可以用PUT
,因為要刪除這個資源時,還是訪問這個
URL。
關於這些功能上有交集的地方,可能後面會有一些更加標準的規範或者協議吧。
最後說下HEAD
和OPTIONS
,HEAD
請求的是資源的元資料,比如一張照片,的元資料則可能包含了,照片拍攝的裝置,地點,時間等。伺服器一般將對應資源的元資料置於響應的報頭集合返回給客戶端,這樣的響應一般不具有主體部分。OPTIONS
則是傳送一種“探測”請求以確定針對某個目標地址的請求必須具有怎樣的約束(比如應該採用怎樣的HTTP方法以及自定義的請求報頭),然後根據其約束髮送真正的請求。
關於過濾篩選,排序和 token 等 query string 是支援使用,和唯一資源的概念並不衝突。
我所理解的無狀態性和唯一資源對 Api Url 的設計指導
舉一個實際的例子,使用者黑名單的 CURD。我們可是設計成
|
如上的 api 設計中,首先如上的 url 設計中,通過授權碼中獲取登入使用者 uid。則是有狀態的了,其次因為所有的使用者訪問的資源都是同一個地址,這與唯一資源的概念是相違背的。如果是無狀態的,那麼就與唯一資源的概念相吻合了。(這只是 restful 所建議的,實際是否需要完全遵守視情況而定)
|
REST的五大特性
-
資源(Resource)
-
資源的表述(Representation)
-
狀態轉移(State Transfer)
-
統一介面(Uniform Interface)
-
超文字驅動(Hypertext Driven)
資源的概念是 RESTful 裡面最重要的一個概念,很容易被我們忽視和誤解,所以就重點闡述了這一特性。
而其他特性,我們日常開發應該都是遵守的,就不再展開說了,需要了解的可以看我的這篇筆記 REST的五個特性 。
Server 端程式碼的基本設計思想
按照 RESTful Api 的規範,嚴格來說根據endpoint
找到在 server 端對映成一個資源物件,例如通過 http://mengkang.net/users/1 找到UserResource
物件
而在這個物件裡對應著該資源支援的 Http 協議的方法。如果一個物件支援7種方式的請求,則類似於:
|