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服務器做者之1、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版本的一些接口