2. 程式人生 > >我的理解 RESTful Api 架構

我的理解 RESTful Api 架構

阿新 • • 發佈：2019-02-07

一些常見的誤解

不要以為 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 就應該是一個資源，不能包含任何動作。

  1. [POST]     http://mengkang.net/users   // 新增
  2. [GET]      http://mengkang.net/users/1 // 查詢
  3. [PATCH]    http://mengkang.net/users/1 // 更新
  4. [PUT]      http://mengkang.net/users/1 // 覆蓋，全部更新
  5. [DELETE]   http://mengkang.net/users/1 // 刪除

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。我們可是設計成

  1. [GET]      /blacklist
  2. [PUT]       /blacklist/{id} #把 id 加入到當前授權使用者的黑名單中
  3. [DELETE]   /blacklist/{id}

如上的 api 設計中，首先如上的 url 設計中，通過授權碼中獲取登入使用者 uid。則是有狀態的了，其次因為所有的使用者訪問的資源都是同一個地址，這與唯一資源的概念是相違背的。如果是無狀態的，那麼就與唯一資源的概念相吻合了。（這只是 restful 所建議的，實際是否需要完全遵守視情況而定）

  1. [GET]      /user/{uid}/blacklist
  2. [PUT]       /user/{uid}/blacklist/{id}  #把 id 加入到當前授權使用者的黑名單中
  3. [DELETE]   /user/{uid}/blacklist/{id}

REST的五大特性

  1. 資源（Resource）

  2. 資源的表述（Representation）

  3. 狀態轉移（State Transfer）

  4. 統一介面（Uniform Interface）

  5. 超文字驅動（Hypertext Driven）

資源的概念是 RESTful 裡面最重要的一個概念，很容易被我們忽視和誤解，所以就重點闡述了這一特性。

而其他特性，我們日常開發應該都是遵守的，就不再展開說了，需要了解的可以看我的這篇筆記 REST的五個特性 。

Server 端程式碼的基本設計思想

按照 RESTful Api 的規範，嚴格來說根據endpoint找到在 server 端對映成一個資源物件，例如通過 http://mengkang.net/users/1 找到UserResource物件

而在這個物件裡對應著該資源支援的 Http 協議的方法。如果一個物件支援7種方式的請求，則類似於：

  1. public class UserResource {
  2. private User user;
  3. public UserResource() {
  4. }
  5. public UserResource(int id) {
  6. //從資料查詢處該使用者的資料
  7. String name = "xxx";
  8. short age = 23;
  9. user = new User(id,name,age);
  10. }
  11. /**
  12. * 獲取單個使用者
  13. * 從 new UserResource(int) 開始
  14. * @return
  15. */
  16. public 

    相關推薦

    我的理解 RESTful Api 架構

    一些常見的誤解 不要以為 RESTful Api  就是設計得像便於 SEO 的偽靜態，例如一個 Api 的 URL 類似於 http://xxx.com/blog/1 ，我們可以通過瀏覽器訪問該 URL 而讀取文章，但是這並不代表著它就是 RESTful

    Rest API 學習筆記 --- 深入理解 Restful API 架構

    wechat:812716131 ------------------------------------------------------ 技術交流群請聯絡上面wechat ----------------------------------------------

    我理解的軟體 架構模式，MVC和分層

    一、緣起     作為程式設計師，很容易天天被業務追逐著，抽不開時間修煉。有一天突然停了一下，忽地就會有一種悵然的感覺，過去的那些日子我學到了什麼？ 有人很認真地說自己有10年經驗，有人笑說你不過是一年經驗用了10年而已。 二、師傅領進門 做人，做事，做架構

    理解 RESTful API 面向資源 冪等性

      如何理解RESTful的冪等性  我來答 分享 舉報瀏覽 3612 次 1個回答 #再見，2018！# 2018要結束了，你還有哪些心願沒完成？？ 最佳答案 熱心網友  2017-07-02 等冪性（Idempotenc

    如何理解RESTful API

    REST的英文全稱 Representation State Transfer : 直譯為表現層狀態轉移. 是通過HTTP協議來描述Web API的約定風格. 什麼是服務? 任何業務服務都可以抽象為物件的狀態維護,基本操作就増刪查改四種. 例如:

    理解 RESTful API 設計規範

    RESTful是目前最流行的API設計規範，它是用於Web資料介面的設計。從字面可以看出，他是Rest式的介面，所以我們先了解下什麼是Rest。 REST與技術無關，它代表的是一種軟體架構風格，REST它是 Representational State Transfer的簡稱，中文的含義是: "表徵狀態轉移

    理解RESTful API

    近日妹子向我求助RESTful API到底是個什麼東西。原因是她們公司一個新啟動的專案因為RESTful API起了爭執。服務端同學堅持要用RESTful API，而前端同學則認為服務端用RESTful API就會讓前端的呼叫變得更麻煩。最終爭議了一下午還是不了了之。有趣的是他們組的大部分人都不太瞭解REST

    理解RESTful架構——Restful API設計指南

    eval 高並發 服務器 ani eric 互聯網通信 info ati 排序 理解RESTful架構 Restful API設計指南 理解RESTful架構 越來越多的人開始意識到，網站即軟件，而且是一種新型的軟件。 這種"互聯網軟件"采用客戶端/服務器模式，建立

    我理解的restful風格的web api

    注:本想法基於C# mvc來說，並不是針對所有的程式語言。 由於開發工具的限制，只能用mvc3開發api，這樣就不能用mvc4的web api了，特意研究了下mvc和web api的區別，最後發現在新版的mvc裡面，他們倆兒竟然合併了，老懷欣慰啊。 HTTP

    理解RESTful架構

    字段 模式 amount 舉例 front cti war can res 越來越多的人開始意識到，網站即軟件，而且是一種新型的軟件。 這種"互聯網軟件"采用客戶端/服務器模式，建立在分布式體系上，通過互聯網通信，具有高延時（high latency）、高並發等特點。

    我的C#跨平臺之旅（二）：開發一組標準的Restful API

    ref 運行 mar margin bruce ora soft left 啟用 添加NuGet引用：Microsoft.AspNet.WebApi.Owin 在啟動類啟用WebApi； 添加一個Controller類，代碼如下： 運行程序

    網上整理的對於Rest和Restful api的理解

    gpo 信息 常用 method 安全 什麽 獲取 正常 stat 一、什麽是Rest? REST不是"rest"這個單詞，而是幾個單詞縮寫 -- REpresentational State Transfer 直接翻譯：表現層狀態轉移，但這個翻譯正常人根本看不懂，找到的一

    軟件架構，WEB - REST架構，RESTful API

    clas www. present lock question pre sent 分享圖片 rest 參考 https://www.zhihu.com/question/27785028/answer/48096396 wiki太學術化了 http://www.ruan

    理解RESTful 架構

    restfu tle tran 什麽 rtb info 接口 調用 崩潰 REST是所有Web應用都應該遵守的架構設計指導原則。 Representational State Transfer，翻譯是”表現層狀態轉化”。 面向資源是REST最明顯的特征，對於同一個資源的一組

    RESTful架構與RESTful API設計

    一、REST的由來 　　REST這個詞是Roy Thomas Fielding博士在他2000年的博士論文中提出的，Fielding將他對網際網路軟體的架構原則定名為REST，即Representational State Transfer的縮寫，翻譯為“表現層狀態轉化”。如果一個架

    什麼是RESTful以及深入理解RESTful架構

    一、起源 REST這個詞，是Roy Thomas Fielding在他2000年的博士論文中提出的。 二、名稱 REST，即Representational State Transfer的縮寫。翻譯過來是"表現層狀態轉化"。 三、資源（Resources） REST的名稱"表現層狀態轉化"中

    restful api 理解

    restful 理解 ：  REST:Representational State Transfer 的縮寫,翻譯:“具象狀態傳輸”。一般解釋為“表現層 狀態轉換”。 REST 是設計風格而不是標準。是指客戶端和伺服器的互動形式。我們需要關注的重點是如何設計 REST 風格的網路介面。 R

    專訪阿里王賢：我所理解的網站架構

      王賢（花名賢哥），淘寶技術部技術專家，在分散式系統架構設計、高併發系統設計、系統穩定性保障等領域積累了較為豐富的實踐經驗，對新技術有濃厚的興趣。 請先和大家介紹下你和目前所從事的工作，以及關注哪些技術領域？ 賢哥：目前在負責某直播平臺，包括整體的技術架構以及業務推廣，

    我對Restful風格的理解

    平常使用增刪改查的時候 一般情況都是用這幾個   比如  addStuInfo  deleteStuInfo  UpadteStuinfo。。。。。 我感覺這樣是不安全的...如果沒有上一步操作的情況下，直接輸入這個網址，就直接把這條資料刪掉了 這時候我發現了Res

    理解RESTful架構(原作者阮一峰）

    越來越多的人開始意識到，網站即軟體，而且是一種新型的軟體。 /div div id="more" class="asset-more" 這種"網際網路軟體"採用客戶端/伺服器模式，建立在分散式體系上，通過網際網路通訊，具有高延時（high latency）、高併發等特點。