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、資源路徑概覽
| 元素 | 描述 |
|---|---|
| sehema | 協議名稱,通常是HTTP或者HTTPS |
| host | (DNS)主機名稱或者IP地址 |
| port | 服務端口 |
| path | 資源地址,使用"/"符號來分隔邏輯上的層次結構 |
| ? | 用來分隔資源地址和查詢字符串符號 |
| queryString | 查詢字符串,方法作用域信息 使用“&”符號來分隔查詢條件 使用都好分隔有次序的作用域信息 使用分號分隔無次序的作用域信息 |
資源地址的路徑變量使用來表達邏輯上的層次結構的,資源和子資源的高興事是自左向右、斜杠分隔的名詞。他們的關系可以是從整體到局部,比如學校到班級,城市到鄉村.可以是從一般到具體,比如一個生物的“門”、“綱”、“目”、“科”等。。。的資源路徑,資源地址具體的可以分為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
- 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 |
在路徑變量里面可以使用標點符號以輔助增強邏輯清晰性。如下表所示
| 功能 | 資源地址 |
|---|---|
| 添加/創建 | 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的圖書列表。
