Restful API 接口設(shè)計(jì)標(biāo)準(zhǔn)及規(guī)范

RESTful概念

理解和評估以網(wǎng)絡(luò)為基礎(chǔ)的應(yīng)用軟件的架構(gòu)設(shè)計(jì)峰伙,得到一個(gè)功能強(qiáng)累澡、性能好拓型、適宜通信的架構(gòu)尽超。REST指的是一組架構(gòu)約束條件和原則官撼。" 如果一個(gè)架構(gòu)符合REST的約束條件和原則,我們就稱它為RESTful架構(gòu)似谁。

REST本身并沒有創(chuàng)造新的技術(shù)傲绣、組件或服務(wù),而隱藏在RESTful背后的理念就是使用Web的現(xiàn)有特征和能力巩踏, 更好地使用現(xiàn)有Web標(biāo)準(zhǔn)中的一些準(zhǔn)則和約束秃诵。雖然REST本身受Web技術(shù)的影響很深, 但是理論上REST架構(gòu)風(fēng)格并不是綁定在HTTP上蛀缝,只不過目前HTTP是唯一與REST相關(guān)的實(shí)例。 所以我們這里描述的REST也是通過HTTP實(shí)現(xiàn)的REST目代。

RestfulAPI 導(dǎo)圖

Restful導(dǎo)圖

理解RESTful

要理解RESTful架構(gòu)屈梁,需要理解Representational State Transfer這個(gè)詞組到底是什么意思,它的每一個(gè)詞都有些什么涵義榛了。我們圍繞資源展開討論在讶,從資源的定義、獲取霜大、表述构哺、關(guān)聯(lián)、狀態(tài)變遷等角度战坤,列舉一些關(guān)鍵概念并加以解釋曙强。

  • 資源與URI
  • 統(tǒng)一資源接口
  • 資源的表述
  • 資源的鏈接
  • 狀態(tài)的轉(zhuǎn)移

資源與URI

URI 表示資源,資源一般對應(yīng)服務(wù)器端領(lǐng)域模型中的實(shí)體類

  • URI 是地址也是資源
  • URI里邊帶上版本號途茫、后綴來區(qū)分表述格式
  • 必備約定
    • 用名詞碟嘴、不用動(dòng)詞
    • 層級結(jié)構(gòu)明確、用/來表示
    • 用?用來過濾資源

統(tǒng)一資源接口

標(biāo)準(zhǔn)HTTP方法包含:GET囊卜、POST娜扇、PUT、DELETE栅组、Patch雀瓢,他們的使用功能如下列表所示

方法作用列表

Get方法執(zhí)行流程原理如下所示

Get方法執(zhí)行流程圖

Put 方法執(zhí)行流程圖如下所示

Put方法執(zhí)行流程圖

安全性和冪等性

  • 1、安全性:不會改變資源狀態(tài)玉掸,可以理解為只讀的刃麸;
  • 2、冪等性:執(zhí)行1次和執(zhí)行N次司浪,對資源狀態(tài)改變的效果是等價(jià)的嫌蚤。
接口 安全性 冪等性
GET
POST × ×
PUT ×
DELETE ×

安全性和冪等性均不保證反復(fù)請求能拿到相同的response辐益。以 DELETE 為例,第一次DELETE返回200表示刪除成功脱吱,第二次返回404提示資源不存在智政,這是允許的。

資源的表述

什么是資源箱蝠?什么是表述续捂?

就本質(zhì)而言,任何足夠重要并被引用的事物都可以是資源宦搬。如果你的用戶“想要建立指向它的超文本鏈接牙瓢,指出或者反對關(guān)于它的斷言,獲取或者緩存它的表述间校,共另外的表述引用它的全部或者部分矾克,給它增加注釋信息,或者對它執(zhí)行某些操作”憔足,(源自《萬維網(wǎng)的架構(gòu)》)胁附,你都應(yīng)該將它定義為資源。

每個(gè)資源必須擁有URL滓彰,在web上控妻,我們使用URL來為每個(gè)資源提供一個(gè)全球唯一的地址,將一個(gè)事物賦以URL揭绑,它就會成為一個(gè)資源弓候。

石榴可以是一個(gè)資源,但是你不可能通過互聯(lián)網(wǎng)傳輸它他匪,數(shù)據(jù)庫中的一條記錄可以是一個(gè)資源菇存,并且可以通過互聯(lián)網(wǎng)傳輸。

當(dāng)客戶端對一個(gè)資源發(fā)起一個(gè)Get請求的時(shí)候邦蜜,服務(wù)器會以一種有效的方式提供一個(gè)采集了資源信息的文檔作為回應(yīng)撰筷。這種資源信息的文檔就是一種表述,一種以機(jī)器可讀的方式對資源當(dāng)前的狀態(tài)進(jìn)行說明

資源有多重表述

一個(gè)資源可以有多種表述畦徘。比如毕籽,有的資源可以有整體概括性的表述,也可以有面面俱到的詳細(xì)表述井辆,又或者可能以JSON格式或者XML格式來表述同一個(gè)資源关筒。

資源的連接

我們知道REST是使用標(biāo)準(zhǔn)的HTTP方法來操作資源的,但僅僅因此就理解成帶CURD的Web數(shù)據(jù)庫架構(gòu)就太過于簡單了杯缺。

這種反模式忽略了一個(gè)核心概念:"超媒體即應(yīng)用狀態(tài)引擎(hypermedia as the engine of application state)"蒸播。 超媒體是什么?

當(dāng)你瀏覽Web網(wǎng)頁時(shí),從一個(gè)連接跳到一個(gè)頁面,再從另一個(gè)連接跳到另外一個(gè)頁面袍榆,就是利用了超媒體的概念:把一個(gè)個(gè)把資源鏈接起來.

要達(dá)到這個(gè)目的胀屿,就要求在表述格式里邊加入鏈接來引導(dǎo)客戶端。在《RESTful Web Services》一書中包雀,作者把這種具有鏈接的特性成為連通性宿崭。下面我們具體來看一些例子。

下面展示的是github獲取某個(gè)組織下的項(xiàng)目列表的請求才写,可以看到在響應(yīng)頭里邊增加Link頭告訴客戶端怎么訪問下一頁和最后一頁的記錄葡兑。 而在響應(yīng)體里邊,用url來鏈接項(xiàng)目所有者和項(xiàng)目地址赞草。

上面的例子展示了如何使用超媒體來增強(qiáng)資源的連通性讹堤。很多人在設(shè)計(jì)RESTful架構(gòu)時(shí),使用很多時(shí)間來尋找漂亮的URI厨疙,而忽略了超媒體洲守。所以,應(yīng)該多花一些時(shí)間來給資源的表述提供鏈接沾凄,而不是專注于"資源的CRUD"梗醇。

狀態(tài)的轉(zhuǎn)移

訪問一個(gè)網(wǎng)站,就代表了客戶端和服務(wù)器的一個(gè)互動(dòng)過程搭独。在這個(gè)過程中婴削,勢必涉及到數(shù)據(jù)和狀態(tài)的變化廊镜;

互聯(lián)網(wǎng)通信協(xié)議HTTP協(xié)議牙肝,是一個(gè)無狀態(tài)協(xié)議。這意味著嗤朴,所有的狀態(tài)都保存在服務(wù)器端配椭。因此,如果客戶端想要操作服務(wù)器雹姊,必須通過某種手段股缸,讓服務(wù)器端發(fā)生"狀態(tài)轉(zhuǎn)化"(State Transfer)。而這種轉(zhuǎn)化是建立在表現(xiàn)層之上的吱雏,所以就是"表現(xiàn)層狀態(tài)轉(zhuǎn)化"敦姻;

客戶端用到的手段,只能是HTTP協(xié)議歧杏。具體來說镰惦,就是HTTP協(xié)議里面,四個(gè)表示操作方式的動(dòng)詞:GET犬绒、POST旺入、PUT、DELETE。它們分別對應(yīng)四種基本操作:GET用來獲取資源茵瘾,POST用來新建資源(也可以用于更新資源)礼华,PUT用來更新資源,DELETE用來刪除資源拗秘;

最后編輯于
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請聯(lián)系作者
  • 序言:七十年代末圣絮,一起剝皮案震驚了整個(gè)濱河市,隨后出現(xiàn)的幾起案子聘殖,更是在濱河造成了極大的恐慌晨雳,老刑警劉巖,帶你破解...
    沈念sama閱讀 219,427評論 6 508
  • 序言:濱河連續(xù)發(fā)生了三起死亡事件奸腺,死亡現(xiàn)場離奇詭異餐禁,居然都是意外死亡,警方通過查閱死者的電腦和手機(jī)突照,發(fā)現(xiàn)死者居然都...
    沈念sama閱讀 93,551評論 3 395
  • 文/潘曉璐 我一進(jìn)店門帮非,熙熙樓的掌柜王于貴愁眉苦臉地迎上來,“玉大人讹蘑,你說我怎么就攤上這事末盔。” “怎么了座慰?”我有些...
    開封第一講書人閱讀 165,747評論 0 356
  • 文/不壞的土叔 我叫張陵陨舱,是天一觀的道長。 經(jīng)常有香客問我版仔,道長游盲,這世上最難降的妖魔是什么? 我笑而不...
    開封第一講書人閱讀 58,939評論 1 295
  • 正文 為了忘掉前任蛮粮,我火速辦了婚禮益缎,結(jié)果婚禮上,老公的妹妹穿的比我還像新娘然想。我一直安慰自己莺奔,他們只是感情好,可當(dāng)我...
    茶點(diǎn)故事閱讀 67,955評論 6 392
  • 文/花漫 我一把揭開白布变泄。 她就那樣靜靜地躺著令哟,像睡著了一般。 火紅的嫁衣襯著肌膚如雪妨蛹。 梳的紋絲不亂的頭發(fā)上屏富,一...
    開封第一講書人閱讀 51,737評論 1 305
  • 那天,我揣著相機(jī)與錄音滑燃,去河邊找鬼役听。 笑死,一個(gè)胖子當(dāng)著我的面吹牛,可吹牛的內(nèi)容都是我干的典予。 我是一名探鬼主播甜滨,決...
    沈念sama閱讀 40,448評論 3 420
  • 文/蒼蘭香墨 我猛地睜開眼,長吁一口氣:“原來是場噩夢啊……” “哼瘤袖!你這毒婦竟也來了衣摩?” 一聲冷哼從身側(cè)響起,我...
    開封第一講書人閱讀 39,352評論 0 276
  • 序言:老撾萬榮一對情侶失蹤捂敌,失蹤者是張志新(化名)和其女友劉穎艾扮,沒想到半個(gè)月后,有當(dāng)?shù)厝嗽跇淞掷锇l(fā)現(xiàn)了一具尸體占婉,經(jīng)...
    沈念sama閱讀 45,834評論 1 317
  • 正文 獨(dú)居荒郊野嶺守林人離奇死亡泡嘴,尸身上長有42處帶血的膿包…… 初始之章·張勛 以下內(nèi)容為張勛視角 年9月15日...
    茶點(diǎn)故事閱讀 37,992評論 3 338
  • 正文 我和宋清朗相戀三年,在試婚紗的時(shí)候發(fā)現(xiàn)自己被綠了逆济。 大學(xué)時(shí)的朋友給我發(fā)了我未婚夫和他白月光在一起吃飯的照片酌予。...
    茶點(diǎn)故事閱讀 40,133評論 1 351
  • 序言:一個(gè)原本活蹦亂跳的男人離奇死亡,死狀恐怖奖慌,靈堂內(nèi)的尸體忽然破棺而出抛虫,到底是詐尸還是另有隱情,我是刑警寧澤简僧,帶...
    沈念sama閱讀 35,815評論 5 346
  • 正文 年R本政府宣布建椰,位于F島的核電站,受9級特大地震影響岛马,放射性物質(zhì)發(fā)生泄漏棉姐。R本人自食惡果不足惜,卻給世界環(huán)境...
    茶點(diǎn)故事閱讀 41,477評論 3 331
  • 文/蒙蒙 一蛛枚、第九天 我趴在偏房一處隱蔽的房頂上張望谅海。 院中可真熱鬧脸哀,春花似錦蹦浦、人聲如沸。這莊子的主人今日做“春日...
    開封第一講書人閱讀 32,022評論 0 22
  • 文/蒼蘭香墨 我抬頭看了看天上的太陽。三九已至蝌诡,卻和暖如春溉贿,著一層夾襖步出監(jiān)牢的瞬間,已是汗流浹背浦旱。 一陣腳步聲響...
    開封第一講書人閱讀 33,147評論 1 272
  • 我被黑心中介騙來泰國打工宇色, 沒想到剛下飛機(jī)就差點(diǎn)兒被人妖公主榨干…… 1. 我叫王不留,地道東北人。 一個(gè)月前我還...
    沈念sama閱讀 48,398評論 3 373
  • 正文 我出身青樓宣蠕,卻偏偏與公主長得像例隆,于是被迫代替她去往敵國和親。 傳聞我的和親對象是個(gè)殘疾皇子抢蚀,可洞房花燭夜當(dāng)晚...
    茶點(diǎn)故事閱讀 45,077評論 2 355

推薦閱讀更多精彩內(nèi)容