restful-api開發(fā)與測試

1、RESTful API開發(fā)與測試,平臺功能模塊簡介,一、RESTful 簡述二、RESTful API編寫規(guī)范三、RESTful API在SSM中的實現(xiàn)四、RESTful API測試,一、RESTful簡述,REST（英文：Representational State Transfer，簡稱REST）描述了一個架構(gòu)樣式的網(wǎng)絡(luò)系統(tǒng)，比如 web 應(yīng)用程序。REST 指的是一組架構(gòu)約束條件和原則。滿足這些約束條件和原則的應(yīng)用程序或

2、設(shè)計就是 RESTful；Web 應(yīng)用程序最重要的 REST 原則是，客戶端和服務(wù)器之間的交互在請求之間是無狀態(tài)的；在服務(wù)器端，應(yīng)用程序狀態(tài)和功能可以分為各種資源。,二、 RESTful API編寫規(guī)范,1、協(xié)議API與用戶的通信協(xié)議，總是使用HTTPs協(xié)議。2、域名應(yīng)該盡量將API部署在專用域名之下：https://api.example.com如果確定API很簡單，不會有進(jìn)一步擴展，可以考慮放在主域名下：htt

3、ps://example.com/api/,二、 RESTful API編寫規(guī)范,3、版本（Versioning）應(yīng)該將API的版本號放入URL：https://api.example.com/v1/ 另一種做法是，將版本號放在HTTP頭信息中，但不如放入URL方便和直觀。4、路徑（Endpoint）路徑又稱"終點"（endpoint），表示API的具體網(wǎng)址。在RESTful架構(gòu)中，每個網(wǎng)址代表一種

4、資源（resource），所以網(wǎng)址中不能有動詞，只能有名詞，而且所用的名詞往往與數(shù)據(jù)庫的表格名對應(yīng)。一般來說，數(shù)據(jù)庫中的表都是同種記錄的"集合"（collection），所以API中的名詞也應(yīng)該使用復(fù)數(shù)。,二、 RESTful API編寫規(guī)范,4、路徑（Endpoint）舉例來說，有一個API提供動物園（zoo）的信息，還包括各種動物和雇員的信息，則它的路徑應(yīng)該設(shè)計成下面這樣：https://api.ex

5、ample.com/v1/zoos https://api.example.com/v1/animals https://api.example.com/v1/employees,二、 RESTful API編寫規(guī)范,5、HTTP動詞對于資源的具體操作類型，由HTTP動詞表示。常用的HTTP動詞有下面五個（括號里是對應(yīng)的SQL命令）：GET（SELECT）：從服務(wù)器取出資源（一項或多項）。 POST（CREAT

6、E）：在服務(wù)器新建一個資源。 PUT（UPDATE）：在服務(wù)器更新資源（客戶端提供改變后的完整資源）。 PATCH（UPDATE）：在服務(wù)器更新資源（客戶端提供改變的屬性）。 DELETE（DELETE）：從服務(wù)器刪除資源。,,二、 RESTful API編寫規(guī)范,5、HTTP動詞還有兩個不常用的HTTP動詞：HEAD：獲取資源的元數(shù)據(jù)。 OPTIONS：獲取信息，關(guān)于資源的哪些屬性是客戶端可以改變的。,,二、

7、 RESTful API編寫規(guī)范,5、HTTP動詞下面是一些例子：GET /zoos：列出所有動物園 POST /zoos：新建一個動物園 GET /zoos/ID：獲取某個指定動物園的信息 PUT /zoos/ID：更新某個指定動物園的信息（提供動物園的全部信息） PATCH /zoos/ID：更新某指定動物園的信息（提供動物園的部分信息） DELETE /zoos/ID：刪除某個動物園 GET /z

8、oos/ID/animals：列出某個指定動物園的所有動物 DELETE /zoos/ID/animals/ID：刪除某個指定動物園的指定動物,,二、 RESTful API編寫規(guī)范,6、過濾信息（Filtering）如果記錄數(shù)量很多，服務(wù)器不可能都將它們返回給用戶。API應(yīng)該提供參數(shù)，過濾返回結(jié)果。下面是一些常見的參數(shù)：?limit=10：指定返回記錄的數(shù)量 ?offset=10：指定返回記錄的開始位置。 ?

9、page=2&per_page=100：指定第幾頁，以及每頁的記錄數(shù)。 ?sortby=name&order=asc：指定返回結(jié)果按照哪個屬性排序，以及排序順序。 ?animal_type_id=1：指定篩選條件 參數(shù)的設(shè)計允許存在冗余，即允許API路徑和URL參數(shù)偶爾有重復(fù)。比如，GET /zoo/ID/animals 與 GET /animals?zoo_id=ID 的含義是相同的,,,二、 RESTf

10、ul API編寫規(guī)范,7、狀態(tài)碼（Status Codes）200 OK - [GET]：服務(wù)器成功返回用戶請求的數(shù)據(jù)，該操作是冪等的（Idempotent）。 201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數(shù)據(jù)成功。 202 Accepted - [*]：表示一個請求已經(jīng)進(jìn)入后臺排隊（異步任務(wù)） 204 NO CONTENT - [DELETE]：用戶刪除數(shù)據(jù)成功。 400 INVALID R

11、EQUEST - [POST/PUT/PATCH]：用戶發(fā)出的請求有錯誤，服務(wù)器沒有進(jìn)行新建或修改數(shù)據(jù)的操作，該操作是冪等的。 401 Unauthorized - [*]：表示用戶沒有權(quán)限（令牌、用戶名、密碼錯誤）。 403 Forbidden - [*] 表示用戶得到授權(quán)（與401錯誤相對），但是訪問是被禁止的。 404 NOT FOUND - [*]：用戶發(fā)出的請求針對的是不存在的記錄，服務(wù)器沒有進(jìn)行操作，該操作是冪等的。

12、406 Not Acceptable - [GET]：用戶請求的格式不可得（比如用戶請求JSON格式，但是只有XML格式）。 410 Gone -[GET]：用戶請求的資源被永久刪除，且不會再得到的。 422 Unprocesable entity - [POST/PUT/PATCH] 當(dāng)創(chuàng)建一個對象時，發(fā)生一個驗證錯誤。 500 INTERNAL SERVER ERROR - [*]：服務(wù)器發(fā)生錯誤，用戶將無法判斷發(fā)出的請求是

13、否成功。,,,,二、 RESTful API編寫規(guī)范,8、錯誤處理（Error handling）如果狀態(tài)碼是4xx，就應(yīng)該向用戶返回出錯信息。一般來說，返回的信息中將error作為鍵名，出錯信息作為鍵值即可：{ error: "Invalid API key" },,,二、 RESTful API編寫規(guī)范,9、返回結(jié)果針對不同操作，服務(wù)器向用戶返回的結(jié)果應(yīng)該符合以下規(guī)范：GET /collect

14、ion：返回資源對象的列表（數(shù)組） GET /collection/resource：返回單個資源對象 POST /collection：返回新生成的資源對象 PUT /collection/resource：返回完整的資源對象 PATCH /collection/resource：返回完整的資源對象 DELETE /collection/resource：返回一個空文檔,,,,二、 RESTful API編寫規(guī)范,

15、10、Hypermedia APIRESTful API最好做到Hypermedia，即返回結(jié)果中提供鏈接，連向其他API方法，使得用戶不查文檔，也知道下一步應(yīng)該做什么。比如，當(dāng)用戶向api.example.com的根目錄發(fā)出請求，會得到這樣一個文檔：{"link": { "rel": "collection https://www.example.com/zoo

16、s", "href": "https://api.example.com/zoos", "title": "List of zoos", "type": "application/vnd.yourformat+json" }},,,,二、 RESTful API編寫規(guī)范,10、Hype

17、rmedia API上面代碼表示，文檔中有一個link屬性，用戶讀取這個屬性就知道下一步該調(diào)用什么API了。rel表示這個API與當(dāng)前網(wǎng)址的關(guān)系（collection關(guān)系，并給出該collection的網(wǎng)址），href表示API的路徑，title表示API的標(biāo)題，type表示返回類型。,,,,三、RESTful API SSM實現(xiàn),1、GET類型API實現(xiàn)2、DELETE類型API實現(xiàn)3、POST類型API實現(xiàn)4、PUT類型A

18、PI實現(xiàn)以上API均采用JSON格式數(shù)據(jù)傳輸,三、RESTful API SSM實現(xiàn),1、GET類型API實現(xiàn),三、RESTful API SSM實現(xiàn),2、DELETE類型API實現(xiàn),三、RESTful API SSM實現(xiàn),3、POST類型API實現(xiàn),三、RESTful API SSM實現(xiàn),4、PUT類型API實現(xiàn),四、RESTful API 測試,1、編碼測試2、工具測試,四、RESTful API 測試,1、編碼測試a、j