RESTful風格的api


網絡應用程序,分為前端和后端兩個部分。當前的發展趨勢,就是前端設備層出不窮(手機、平板、桌面電腦、其他專用設備......)。

因此,必須有一種統一的機制,方便不同的前端設備與后端進行通信。這導致API構架的流行,甚至出現"API First"的設計思想。

RESTful API是目前比較成熟的一套互聯網應用程序的API設計理論。

本文部分圖文摘自於,https://www.jianshu.com/p/43dae0b83755

1. Rest來源:

REST:是一組架構約束條件和原則,REST是Roy Thomes Fielding在他2000年的博士論文中提出的。Roy Thomas Fielding是

HTTP協議(v1.0和v1.1)的主要設計者、Apache服務器作者之一、Apache基金會第一任主席。

2. 什么是REST

REST不是”rest”這個單詞,而是幾個單詞的縮寫 REpresentation State Transfer,直接翻譯:表現層狀態轉移,這個翻譯不太

好理解。網上找到一個比較通俗的說法是:URL定位資源,用HTTP動詞(GET,POST,DELETE,PUSH等)描述操作

3. 什么是Restful

基於REST構建的API就是Restful風格。

近年隨着移動互聯網的發展,各種類型的客戶端層出不窮,Restful可以通過一套統一的接口為PC、微信(H5)、IOS和Android提供服務,

這樣的接口不需要前端樣式,只提供數據。Restful架構如下:

 

4. 如何設計Restful風格的API

  RestfulAPI就是由后台(SERVER端)來提供接口,前端來調用。前端調用API向后台發起HTTP請求,后台響應請求將處理結果反饋給前

端。也就是說Restful 是典型的基於HTTP的協議。那么RESTful API有哪些特征呢?

(1).Resource資源

  首先是弄清楚資源的概念。資源就是網絡上的一個實體、一段文本、一張圖片或者一首歌曲。資源總是要通過一種載體來反應它的內容。

文本可以用TXT,也可以用HTML或者XML、圖片可以用JPG格式或者PNG格式,JSON是現在最常用的資源表現形式。

(2).統一接口

  Restful風格的數據元操作CRUD(create,read,update,delete)分別對應HTTP方法:GET用來獲取資源,POST用來新建資源(也可

以用於更新資源),PUT用來更新資源,DELETE用來刪除資源,這樣就統一了數據操作的接口。

(3).使用HTTP狀態碼 

  當客戶端通過API向服務器發出請求時,客戶端應該知道反饋,無論是失敗,成功還是請求錯誤。 HTTP狀態代碼是一系列標准化代碼,

針對http請求的可能會發生的各種情況。 服務器應始終返回正確的狀態代碼。

很多人喜歡把錯誤信息放在返回值中,典型的Code和Message,其實比較Low。

下面是Http狀態碼,可以合理利用處理各種請求反饋,將http自身的錯誤和服務器內部的錯誤,有一個很好的區分。

2xx(成功類別)

200 Ok表示GET,PUT或POST成功的標准HTTP響應。

201 Created每當創建新實例時,都應返回此狀態代碼。 例如,使用POST方法創建新實例時,應始返回201狀態代碼。

204 No Content表示請求已成功處理,但未返回任何內容。

3xx(重定向類別)

304 Not Modified表示客戶端已在其緩存中有響應。 因此無需再次傳輸相同的數據。 

4xx(客戶端錯誤類別)

這些狀態代碼表示客戶端已提出錯誤請求。

400 Bad Request表示未處理客戶端的請求,因為服務器無法理解客戶端要求的內容。

401 Unauthorized表示不允許客戶端訪問資源,並應使用所需憑據重新請求。

403 Forbidden表示請求有效且客戶端已通過身份驗證,但不允許客戶端出於任何原因訪問該頁面或資源。例如,有時不允許授權客戶端訪

問服務器上的目錄。

404 Not Found表示請求的資源現在不可用。

410 Gone表示已移動的請求資源不再可用。

5xx(服務器錯誤類別)

500內部服務器錯誤表示請求有效,但服務器完全混淆,並要求服務器提供某些意外情況。

503 Service Unavailable表示服務器已關閉或無法接收和處理請求。大多數情況下,例如服務器正在進行維護。

(4).合理利用Http本身的方法

  HTTP已定義了幾組方法,這些方法指示要對資源執行什么類型的操作。我們制定web接口,要合理利用http的方法!URL是說白了,就是

一個句子,其中資源是名詞,HTTP方法是動詞。

GET 方法從資源請求數據,不應產生任何其他作用。

例如/schools/清華/students,返回所有清華大學的學生 

POST方法請求服務器在數據庫中創建資源,主要是在提交Web表單時。

/schools/清華/students/張三,在清華大學的學生資源,新增一個張三的學生。

POST是非冪等的,這意味着多個請求將具有不同的效果。 

PUT方法請求服務器更新資源或創建資源(如果不存在)。

/schools/清華/students/張三, 對清華大學下的學生資源中,更新或者創建張三。

PUT是冪等的,這意味着多個請求將具有相同的效果。

DELETE方法請求從數據庫中刪除資源或其實例。

/schools/清華/students/張三,從清華大學的學生集合中,刪除學生張三的資源。

(5).無狀態

  所謂無狀態即所有的資源都可以URI定位,而且這個定位與其他資源無關,也不會因為其他資源的變化而變化。Restful 是典型的基於

HTTP的協議,HTTP連接最顯著的特點是客戶端發送的每次請求都需要服務器回送響應,在請求結束后,會主動釋放連接。從建立連接到關閉

連接的過程稱為“一次連接”。前面一次請求與后面一次請求沒有必然的聯系,所以是無狀態的。

(6).使用JSON作為通信格式

  JSON閱讀性更高,擴展性更強,適合各種環境和語言進行解析,現在大的互聯網公司,對外提供的API基本都使用JSON。

(7).搜索,排序,過濾和分頁

  所有這些操作都只是對一個數據集的查詢。將不會有新的API集來處理這些操作。我們需要使用GET方法API附加查詢參數。

下面看幾個例子:

GET /schools ? search = 清華大學 在大學集合中,搜索清華大學

GET /schools ? sort = rank_asc 按照升序排列學校

GET /schools ? location = 北京 按照城市對學校過濾

GET /schools ? page=6 獲取第六頁的學校列表

(8).使用版本控制

例如下面兩個版本地址:

http://api.yourservice.com/v1/schools/清華

http://api.yourservice.com/v2/schools/清華 

在API上加入版本信息可以有效的使用戶訪問正確的API,v2是新開發功能,開發階段,讓所有用戶訪問v1,等開發完成統一切到v2。

可以有效的跨版本訪問,例如在v2版本,還需要訪問v1版本的一些接口


免責聲明!

本站轉載的文章為個人學習借鑒使用,本站對版權不負任何法律責任。如果侵犯了您的隱私權益,請聯系本站郵箱yoyou2525@163.com刪除。



 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM