Unit 10: RESTful Service 使用 JAX-RS 2.0 – Basic Concepts

3 minute read

JSF 教學

HTTP 請求結構回顧

HTTP 請求的結構 [10]:

1
2
3
4

<method> <request-URL> <version>
<headers>
  
<entity-body>

Example:

1
2
3
4

POST http://www.example.com HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8
  
title=test&sub%5B%5D=1&sub%5B%5D=2&sub%5B%5D=3

什麼是 RESTful Service

REST Style Architecture

Fielding, R. T. 於 2000 提出 REST Style Architecture. Representational State Transfer (REST) is an architectural style for building distributed systems. The Web is an example for such a system.

他認為超本文(hypertext)是同時對資訊的呈現(presentation)及控制(control), 使得資訊藉由使用者得到選擇及選擇行動變得變得有可用性(affordance).

REST Style Architecture 觀點下的 WWW 世界:

  • Resource: 每一台電腦或可以提供資訊的應用程式被視為是 Resource
  • Resource URL: 每個 Resource 在 WWW 中有唯一的 URL 表示其位置
  • Representational State: 資源具有可表徵的狀態, 狀態可用文字表示.

RESTful-Triangle (REST 金三角) 概念[4]:

  • Nouns 名詞：用來表示資源的名稱。每一個網路上的資源應該僅有一個唯一的識別位置，通常使用 URL 表示
  • Verbs 動詞：描述了對 Nouns 名詞 (資源 URL) 的操作動作。比如使用 http 的方法對網路上的資源進行查詢、新增、修改、刪除等動作。HTTP 的方法包括: GET, POST, PUT, 及 DELETE.
  • Content Types 資源呈現方式：比如取得某一個 URL 文章的 HTML 格式、或者 XML 格式，同樣的 URL 資源可以有不同型態的表現方式。

Fig Source: [5]

RESTful Service 是依照 REST Style Architecture 設計的服務。 RESTful Web Service 指 Web Service 其設計架構符合 REST Style Architecture。

REST Style 的服務存取

在 HTTP 協定下實現的 REST Style 服務的存取 假設有一公司開放網址 http://rest.example.com/, 其下有兩個資源:

  • http://rest.example.com/books: 所有的書本的資訊
  • http://rest.example.com/books/{id}: 特定書本的資訊

配合不同的 HTTP 方法所代表的意思

資源名稱 HTTP 方法 意義
http://rest.example.com/books GET 取得所有的書本資訊。回傳的資料放在 Response 中
http://rest.example.com/books POST 新增一群書本資訊。Server 回傳新增資料的 URI。
http://rest.example.com/books PUT 新增一群書本資訊，若不存在。若己存在，替換原來的資料
http://rest.example.com/books DELETE 刪除一群書本資訊。
資源名稱 HTTP 方法 意義
http://rest.example.com/books/B101 GET 取得書本 B101 資訊。回傳的資料放在 Response 中
http://rest.example.com/books/add POST 新增一群書本資訊。Server 回傳新增資料的 URI, 例如: http://rest.example.com/books/B101 。
http://rest.example.com/books/B101 PUT 更新 書本 B101 資訊。若不存在，建立書本 B101 資料。
http://rest.example.com/books/B101 DELETE 刪除書本 B101 資訊。

JAX-RS API

Java API for RESTful Web Services (JAX-RS) 是 Java EE 對 RESful Web Service 的解決方案所制定的標準。

JAX-RS 的實作有[6]:

  • Jersey [7] (Glassfish Server 中使用的版本)
  • Apache CXF
  • 其它參考 [6]

從 Request-Response 的角度來看 REST 下 Client 及 Server 間的溝通。 Client 2 對資源 /order/12345 進行 POST 操作，其資料的 content-type 為 form-urlencoded。這個請求被對應到 Warehouse endpoint。Warehouse 會新增一筆資料，並以非同步的方式回覆 Client 端。

Warehouse endpoint 屬於 JAX-RS 的 Provider; Client 2 屬於 JAX-RS Client。

Fig Source: P350 in [8]

若從 JAX-RS 的角度來看:

Fig Source: [9]

撰寫 JAX-RS 應用程式

Basic Steps

  1. 定義的資源名稱 (Resource Name), 包含: URI 樣式(pattern)、輸入及其 content type、輸出及其 content type
  2. 建立 Resource Class, 用來代表 JAX-RS 的 endpoint
    • 註記(annotate) root resource path: @Path
  3. 建立 Resource class method, 用來對映 http methods
    • 註記 Class method 所對映的 http methods: @GET, @POST, @PUT, @DELETE。
    • 註記 Class method 的可以接受的來自 Cliend 的內容型態: @Consumes; 註記回應給 Client 時的內容型態 @Produce

Code Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import javax.ws.rs.GET;
import javax.ws.rs.Produces;
import javax.ws.rs.Path;
  
// The Java class will be hosted at the URI path "/helloworld"
// The URL will be http://hostname/web_context/helloworld
@Path("/helloworld")
public class HelloWorldResource {
  
    // The Java method will process HTTP GET requests
    @GET
    // The Java method will produce content identified by the MIME Media
    // type "text/plain"
    @Produces("text/plain")
    public String getClichedMessage() {
        // Return some cliched textual content
        return "Hello World";
    }
}

實作練習

使用 Netbeans 產生 RESTful Applicatioin 及其測試工具

Step 使用 Netbeans 產生新的專案。 選擇 REST: HELLO WORLD (Java EE 6) 的專案樣板。

Step 建立後，會自動產生 helloworld package，package 內有三個 class:

  • ApplicationConfig class: 用來對 RESTful application 進行設定用的類別。
  • HelloWorldResource class: 是 resource class.
  • NameStorageBean class: 是 Singleton session bean，用來儲存資料，扮演 repository 的角色。

Step 測試此專案。滑鼠右鍵點選專案名稱，選擇項目 Test RESTful Web Service。

Step 在 Configure REST Test Client 視窗中，選擇選項 Web Test Client in Project，選擇先前建立的專案目錄。

Step 完成後，NetBeans 會在選擇的專案的 Web Pages 目錄產生 test-restbeans.html 及所需要的 CSS、JS、和其他的圖片資源。之後，會自動部署應用程式，並瀏覽到 test-restbeans.html。

Step 除了使用 test-restbeans.html 進行測試外，也可以使用 curl 指令進行測試。

使用 curl linux 指令進行測試:

1
2
3
4

# Get
curl "http://localhost:8080/jsf_under_unit10/resources/greeting"
# Put 
curl -X PUT --header "Content-Type: text/plain" --data "Mary" "http://localhost:8080/jsf_under_unit10/resources/greeting"

References

  1. 什麼是REST跟RESTful?
  2. [不是工程師] 休息(REST)式架構? 寧靜式(RESTful)的Web API是現在的潮流？
  3. Java Tutorial 第六堂（1）REST 與 JAX-RS
  4. RESTful API 設計準則與實務經驗 - Soul & Shell Blog
  5. Representational State Transfer (REST) ; Erik Wilde ; UC Berkeley School of Information
  6. Java API for RESTful Web Services - Wikipedia
  7. Jersey
  8. Pilgrim, P.A. (2013). Java EE 7 Developer Handbook. Packt Publishing.
  9. Creating RESTful Web Services with JAX-RS - Developer.com
  10. 四种常见的 POST 提交数据方式, JerryQu 的小站
  11. Chapter 15. JAX-RS Resource Locators and Sub Resources
  12. Subresources and Runtime Resource Resolution - The Java EE 6 Tutorial
  13. Chapter 13 Building RESTful Web Services with JAX-RS (The Java EE 6 Tutorial)
  14. 使用curl指令測試REST服務
  15. Sending API requests using cURL

[Top]

Updated:

You May Also Enjoy