PUT方法
PUT方法是一種寫操作的HTTP請求,REST使用HTTP的PUT方法更新或新增資源
1、更新資源
REST知識風格,不是技術規範或者標準,所以有些實現REST的細節明確的定義,這對實踐而言,不可避免會產生某些誤解,比如在建立和更新某個資源的時候,開發者比較迷茫的是何時該用HTTP的PUT方法,何時使用POST方法,為了解決這一問題,我們首先應該知道PUT方法的特性,PUT方法是冪等的,即多次插入或者更新同一份資料,在伺服器端對資源狀態所產生的改變是相同的,PUT方法是不安全的,有些動作的HTTP方法都不是安全的。我們知道,由於使用同一份資料向伺服器請求更新某一資源,得到的結果應該總是相同的,因此對於更新操作,使用PUT是沒有疑問的。
2、新增資源
建立操作通常每次得到的結果是不同的,因為伺服器端的業務層邏輯通常要求資料的主鍵欄位要麼來自於業務平臺自增一個邏輯值,要麼來自於資料庫中的主鍵自增,因此,相同的資料每一次提交到伺服器端,都會為資料新增一個新的主鍵值,也就是建立一個主鍵值不同的新資源（如果沒有業務或者外來鍵衝突）。所以,建立操作通常應當設計為POST方法的API,唯有一種場景應當使用PUT方法來設計API,即客戶端在發起建立請求時候,在同一份資料中總可以提供唯一的主鍵值,伺服器不會對其進行修改,這樣的建立請求確保了冪等性,不應該在使用PUT請求
資源地址設計
資源地址的設計對整個REST式的Web服務至關重要,設計系統的可用性和可擴充套件性等諸多方面的表現
1、資源路徑概覽
資源地址的路徑變數使用來表達邏輯上的層次結構的,資源和子資源的高興事是自左向右、斜槓分隔的名詞。他們的關係可以是從整體到區域性,比如學校到班級,城市到鄉村.可以是從一般到具體,比如一個生物的“門”、“綱”、“目”、“科”等。。。的資源路徑,資源地址具體的可以分為5個部分,以sehema://host:port/path?queryString為例,如下表格
| 元素 | 描述 |
|---|---|
| sehema | 協議名稱,通常是HTTP或者HTTPS |
| host | (DNS)主機名稱或者IP地址 |
| port | 服務埠 |
| path | 資源地址,使用"/"符號來分隔邏輯上的層次結構 |
| ? | 用來分隔資源地址和查詢字串符號 |
| queryString | 查詢字串,方法作用域資訊 使用“&”符號來分隔查詢條件 使用都好分隔有次序的作用域資訊 使用分號分隔無次序的作用域資訊 |
一個典型的URI如上表所示,包括協議名稱、主機名稱、服務埠、資源地址和查詢字串5個部分,其中資源地址部分,根據具體部署的不同或有差別 http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/books/book?id=1
- requestURL
- http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/books/book?id=1
- ContextPath
- simple-service-webapp-spring-jpa-jquery
- ServletPath
- webapi
- PahtInfo
- books/book
通常使用ContextPath、ServletPaht和PathInfo來細分資源地址。
- ContextPath: 上下文名稱,通常和部署伺服器的配置或者REST服務的web.xml配置有關。
- ServletPath: 是Servlet的名稱,與REST服務中定義的@ApplicationPath註解或者web.xml的而配置有關
JAX-RS2定義了@Path註解來定義資源地址
- PathInfo：資源路徑資訊,與資源類、子類及勒種的方法蒂尼的@Path註解有關
2、資源地址和作用域
在路徑變數裡面可以使用標點符號以輔助增強邏輯清晰性。如下表所示
| 功能 | 資源地址 |
|---|---|
| 新增/建立 | POST/books PUT/books/{id} |
| 刪除 | DELETE/books/{id} |
| 修改/更新 | PUT/books/{id} |
| 查詢全部 | GET/books HTTP1.1 |
| 主鍵查詢 | GET/books/{id} HTTP1.1 GET /books?id=12334 |
| 分頁作用域查詢 | GET/books/{id} HTTP1.1 GET /books/01,2002-12,2014 GET /books/restful;program=java;type=web GET /books?limit=100&sort=bookname |
- 問號(?) 是用來分隔資源路徑地址和查詢字串,與符號(&)是用來分隔查詢條件的引數,示例程式碼如下
GET /books?start=0&size=19
複製程式碼程式碼解釋：開始行引數為0,查詢的條目是19,及從第0行開始查詢去19條資料
- 逗號(,)是用來分隔有次序的作用域資訊,需要注意的是逗號分隔符的邏輯上的順序資訊,這種順序可以是約定俗成的,比如先寫經度然後緯度;也可以是系統約定的,比如年、月、日、時等。 舉例來說：按時間區域查詢圖書,日期資訊在資源地址中是採用月、年順序,程式碼如下
GET /books/01,2002-12,2014
複製程式碼程式碼解釋:查詢2002年1月到2014年12月的這個時間段的圖書,這個例子中還使用到了連字元(-),有時候也可以使用下劃線(_)來做邏輯上的輔助分隔。
- 分號(;)是用來分隔無次序的作用域資訊,通常這些資訊是邏輯上並列存在的,比如並列的查詢條件,示例程式碼如下
GET /books/restful;program=java;type=web
複製程式碼程式碼解釋:查詢滿足圖書內容為restful的,石巨集的程式語言是java的講述的型別是web的圖書列表。