resful協議1

1、重要概念：

RESTFul API已是如今互聯網裏對外開放接口的主流模式，可參考：git

豆瓣API https://developers.douban.com/wiki/?title=api_v2github

GitHub https://developer.github.com/v3/數據庫

分享關於resful協議：json

https://www.jianshu.com/p/294fcc945db7api

https://blog.igevin.info/posts/restful-api-get-started-to-write/數組

1. resful協議簡介

1 RESTful架構風格最初由Roy T. Fielding（HTTP/1.1協議專家組負責人）在其2000年的博士學位論文中提出。HTTP就是該架構風格的一個典型應用。從其誕生之日開始，它就因其可擴展性和簡單性受到愈來愈多的架構師和開發者們的青睞。一方面，隨着雲計算和移動計算的興起，許多企業願意在互聯網上共享本身的數據、功能；另外一方面，在企業中，RESTful API（也稱RESTful Web服務）也逐漸超越SOAP成爲實現SOA的重要手段之一。時至今日，RESTful架構風格已成爲企業級服務的標配。 2 
3 REST即Representational State Transfer的縮寫，可譯爲"表現層狀態轉化」。REST最大的幾個特色爲：資源、統一接口、URI和無狀態。
4 
5 restful是一種架構風格，其核心是面向資源

resful協議簡介

首先restful是一種軟件架構風格或者說是一種設計風格，並非標準，它只是提供了一組設計原則和約束條件，主要用於客戶端和服務器交互類的軟件。緩存

 1 resful的六個限制(約束)和這些約束的優勢：  2 
 3 1.客戶-服務器（Client-Server）客戶端服務器分離  4 優勢，提升用戶界面的便攜性（操做簡單）  5 經過簡化服務器提升可伸縮性（高性能，低成本）  6 容許組件分別優化（可讓服務端和客戶端分別進行改進和優化）  7 
 8 2.無狀態（Stateless）  9 從客戶端的每一個請求要包含服務器所須要的全部信息 10 優勢： 11 提升可見性（能夠單獨考慮每一個請求） 12 提升了可靠性（更容易從局部故障中修復） 13 提升可擴展性（下降了服務器資源使用） 14 
15 3.緩存（Cachable） 16 服務器返回信息必須被標記是否能夠緩存，若是緩存，客戶端可能會重用以前的信息發送請求。 17 優勢： 18 減小交互次數 19 減小交互的平均延遲 20 
21 4.分層系統（Layered System） 22 系統組件不須要知道與他交流組件以外的事情。封裝服務，引入中間層。 23 優勢： 24 限制了系統的複雜性 25 提升可擴展性 26 
27 5.統一接口（Uniform Interface） 28 優勢： 29 提升交互的可見性 30 鼓勵單獨改善組件 31 
32 6.支持按需代碼（Code-On-Demand 可選） 33 優勢： 34 提升可擴展性

resful的六個限制(約束)和這些約束的優勢：

二、resful的10大設計規範

總結一下什麼是RESTful架構：安全

（1）每個URI表明一種資源；服務器

（2）客戶端和服務器之間，傳遞這種資源的某種表現層；restful

（3）客戶端經過四個HTTP動詞，對服務器端資源進行操做，實現"表現層狀態轉化"。

一、路徑（接口命名）

在RESTful架構中，每一個網址表明一種資源（resource），因此在url接口中儘可能要使用名詞，不要使用動詞，並且所用的名詞每每與數據庫的表格名對應。

通常來講，數據庫中的表都是同種記錄的"集合"（collection），因此API中的名詞也儘可能使用複數。

二、動做

能夠根據Http不一樣的method，進行不一樣的資源操做（5種方法：GET / POST / PUT / DELETE / PATCH）

1 GET （SELECT）：從服務器檢索特定資源，或資源列表。 2 POST （CREATE）：在服務器上建立一個新的資源。 3 PUT （UPDATE）：更新服務器上的資源，提供整個資源。 4 PATCH （UPDATE）：更新服務器上的資源，僅提供更改的屬性。 5 DELETE （DELETE）：從服務器刪除資源。

五種方法

三、版本控制

版本控制：API必定要有版本號。不必定要在URL路徑在，能夠再hearder加也能夠在 url參數加。不過我認爲放到路徑好一些。如：http://api.example.com/v1.0/foo

四、過濾信息（Filtering）

若是記錄數量不少，服務器不可能都將它們返回給用戶。API應該提供參數，過濾返回結果。

1 ?limit=10：指定返回記錄的數量 2 ?offset=10：指定返回記錄的開始位置。 3 ?page_number=2&page_size=100：指定第幾頁，以及每頁的記錄數。 4 ?sortby=name&order=asc：指定返回結果按照哪一個屬性排序，以及排序順序。 5 ?animal_type_id=1：指定篩選條件 6 參數的設計容許存在冗餘，即容許API路徑和URL參數偶爾有重複。好比， 7 GET /zoo/ID/animals 與 GET /animals?zoo_id=ID 的含義是相同的。

常見參數

五、url中能夠體現這是個API接口

https://www.example.com/api/

六、狀態碼（Status Codes）

獲得的響應應該包含狀態碼：

1 1xx 信息，請求收到，繼續處理。範圍保留用於底層HTTP的東西，你極可能永遠也用不到。 2 2xx 成功，行爲被成功地接受、理解和採納 3 3xx 重定向，爲了完成請求，必須進一步執行的動做 4 4xx 客戶端錯誤，請求包含語法錯誤或者請求沒法實現。範圍保留用於響應客戶端作出的錯誤，例如。他們提供不良數據或要求不存在的東西。這些請求應該是冪等的，而不是更改服務器的狀態。 5 5xx 範圍的狀態碼是保留給服務器端錯誤用的。這些錯誤經常是從底層的函數拋出來的，甚至 6 開發人員也一般無法處理，發送這類狀態碼的目的以確保客戶端得到某種響應。 7 當收到5xx響應時，客戶端不可能知道服務器的狀態，因此這類狀態碼是要儘量的避免。

狀態碼種類

 1 服務器向用戶返回的狀態碼和提示信息，常見的有如下一些（方括號中是該狀態碼對應的HTTP動詞）。  2 
 3 200 OK - [GET]：服務器成功返回用戶請求的數據，該操做是冪等的（Idempotent）。  4 201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數據成功。  5 202 Accepted - [*]：表示一個請求已經進入後臺排隊（異步任務）  6 204 NO CONTENT - [DELETE]：用戶刪除數據成功。  7 400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發出的請求有錯誤，服務器沒有進行新建或修改數據的操做，該操做是冪等的。  8 401 Unauthorized - [*]：表示用戶沒有權限（令牌、用戶名、密碼錯誤）。  9 403 Forbidden - [*] 表示用戶獲得受權（與401錯誤相對），可是訪問是被禁止的。 10 404 NOT FOUND - [*]：用戶發出的請求針對的是不存在的記錄，服務器沒有進行操做，該操做是冪等的。 11 406 Not Acceptable - [GET]：用戶請求的格式不可得（好比用戶請求JSON格式，可是隻有XML格式）。 12 410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再獲得的。 13 422 Unprocesable entity - [POST/PUT/PATCH] 當建立一個對象時，發生一個驗證錯誤。 14 500 INTERNAL SERVER ERROR - [*]：服務器發生錯誤，用戶將沒法判斷髮出的請求是否成功。 15 502 網關錯誤 16 503 Service Unavailable 17 504 網關超時

常見狀態碼

七、應該有返回值，並且格式爲統一的json格式

針對不一樣操做，向用戶返回的結果應該符合規範：

GET/collections：返回資源對象的列表（數組） GET/collections/identity：返回單個資源對象 POST/collections：返回新生成的資源對象 PUT/collections/identity：返回完整的資源對象 PATCH/collections/identity：返回被修改的屬性 DELETE/collections/identity：返回一個空文檔

返回結果

八、統一描述錯誤和自定義錯誤信息

當客戶端發生錯誤時，須要具體告訴客戶端錯誤的信息這個信息用3個東西來定義：錯誤碼，錯誤信息，當前URL，也能夠超過此三個添加本身的錯誤信息。

九、返回結果中要提供幫助連接，即API最好作到Hypermedia。

十、在url接口中推薦使用Https協議，讓網絡接口更加安全

（Https是Http的安全版，即HTTP下加入 SSL層，HTTPS的安全基礎是SSL，所以加密的詳細內容就須要SSL（安全套接層協議））