Restful風格接口淺析

爲何使用RESTful
1．JSP技術可讓咱們在頁面中嵌入Java代碼，可是這樣的技術實際上限制了咱們的開發效率，由於須要咱們Java工程師將html轉換爲jsp頁面，並寫一些腳本代碼，或者前端代碼。這樣會嚴重限制咱們的開發效率，也不能讓咱們的java工程師專一於業務功能的開發，因此目前愈來愈多的互聯網公司開始實行先後端分離。
2．近年隨着移動互聯網的發展，各類類型的Client層出不窮，RESTful能夠經過一套統一的接口爲Web，iOS和Android提供服務。另外對於廣大平臺來講，好比微博開放平臺，微信開放平臺等，它們不須要有顯式的前端，只須要一套提供服務的接口，RESTful無疑是最好的選擇。RESTful架構以下：

5、如何設計Restful風格的API
1.路徑設計
 —>在RESTful架構中，每一個網址表明一種資源（resource），因此網址中不能有動詞，只能有名詞，並且所用的名詞每每與數據庫的表名對應，通常來講，數據庫中的表都是同種記錄的」集合」（collection），因此API中的名詞也應該使用複數。
 —>舉例來講，有一個API提供動物園（zoo）的信息，還包括各類動物和僱員的信息，則它的路徑應該設計成下面這樣。

   https://api.example.com/v1/zoos
   https://api.example.com/v1/animals
   https://api.example.com/v1/employees

 

1 你一直在錯誤的使用http協議

 

如今微服務真是火的一塌糊塗！大街小巷，逢人必談微服務，各路大神紛紛忙着把自家的單體服務拆解成多個Web微小服務！而做爲微服務之間通訊的橋樑，Web API的設計就顯得很是重要。

 

Http是目前互聯網使用最多的協議，沒有之一！可是做爲Http協議創始人之一的Roy Fielding認爲，過去十年，你們都在錯誤的使用Http協議。刪除一個數據，路徑每每是 delete/{id} , 更新一條數據，路徑每每被定義爲update/{id}。你已經被Roy在內心默默的鄙視了！

 

Roy Fielding提出了一種用於設計Web服務的架構方法，稱爲Representational State Transfer（REST）。REST的概念是將API結構分離爲操做和資源。使用HTTP方法GET、DELETE、POST和PUT操做資源。

 

設計糟糕的REST API = 浪費時間！

 

優秀的API就像一位藝術家在舞臺上表演，其用戶就是觀衆，能給全部人帶來賞心悅目的美感！

 

 

2 REST API裏面的術語

 

 

Resource（資源）是指表明某種東西的對象，它具備一些與之相關的數據，而且能夠有一組方法對其進行操做。 例如。 學校，班級和學生是資源，刪除，添加，更新是要對這些資源執行的操做。

 

Collections（集合）是一組資源，例如，211大學是全國211所優質大學的集合。

 

URL（統一資源定位符）是能夠經過其定位資源的路徑，而且能夠對其執行某些操做。

 

 

3 API設計使用名詞，而不是動詞

 

例如獲取全部學生，可能經過以下api: 

/getAllStudents,

增長學生，多是：/addNewStudent

更新學生，多是：/updateStudent

刪除學生，多是：/deleteStudent

刪除全部學生，多是：/deleteStudents

獲取三好學生，多是：/getSanHaoStudents

更多操做......等等。

 

對於不一樣的操做，會衍生出愈來愈多的API接口，數量不停的增多，接口將會變得混亂和難以維護。

有沒有感受哪裏不對？

URL應僅包含資源（名詞）而不包含動做或者動詞！增長學生的API路徑：/addNewStudent，包含操做addNew以及資源名稱Student。

 

正確的方法是什麼？

/schools ，是一個很好的例子，不包含任何動做。可是咱們怎麼告訴服務器，有關學校資源的操做呢，例如增長，刪除或者更新學校？ 

這就是HTTP方法(GET,POST,DELETE,PUT)(也成爲動詞)扮角色的地方！API接口的資源應始終爲複數，若是咱們要訪問資源的一個實例，咱們能夠在URL中傳遞id或者name之類的。

 

GET 路徑 /schools 獲取全部的學校

GET 路徑 /schools/清華 獲取名字叫清華大學的詳細信息

DELETE 路徑 /schools/清華 從學校列表中，刪除清華大學

 

資源和資源之間可能有父子關係，那又應該如何設計呢？例如學校的學生，下面是一些示例：

 

GET /schools/清華/students  獲取清華大學的全部學生

GET /schools/清華/students/張三 獲取清華大學名字叫張三的學生的詳細信息

DELETE /schools/清華/students/張三 刪除清華大學名字叫張三的學生

 

 

4 合理利用Http自己的方法

 

 

HTTP已定義了幾組方法，這些方法指示要對資源執行什麼類型的操做。咱們制定web接口，要合理利用http的方法！

 

URL是說白了，就是一個句子，其中資源是名詞，HTTP方法是動詞。

 

GET 方法從資源請求數據，不該產生任何其餘做用。

例如/schools/清華/students，返回全部清華大學的學生

 

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

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

POST是非冪等的，這意味着多個請求將具備不一樣的效果。

 

PUT方法請求服務器更新資源或建立資源（若是不存在）。

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

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

 

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

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

 

5 使用JSON做爲通訊格式

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

 

6 使用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表示服務器已關閉或沒法接收和處理請求。大多數狀況下，例如服務器正在進行維護。

 

 

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版本的一些接口

 

9 總結

1，API接口都用小寫

2，使用JSON通訊

3，API帶版本控制，好比v1,v2

4，使用Token令牌進行鑑權

5，路徑中單詞鏈接使用中劃線-

6，使用HTTP自身的方法表示增刪改查資源， GET：查詢，POST：新增，PUT：更新，DELETE：刪除

7，合理使用HTTP狀態碼，200，201，400，401，403，500。好比401表示用戶身份認證失敗，403表示你驗證身份經過了，可是無權限操做資源。