JEESZ REST 服務介面文件

1、 引言.....................................................................................................................................

1.1、 REST 介紹..................................................................................................................

1.1、 編寫目的……………………………………………………………………………..

1.2、 編寫原則.....................................................................................................................

1.3、 變更歷史.....................................................................................................................

2、 服務使用說明

2.1、 當前系統已經提供的服務………………………………………………………….

2.2、 GET 方式呼叫服務…………………………………………………………………

2.3、 POST 方式呼叫服務………………………………………………………………..

2、 我的收藏服務列表.............................................................................................................

2.1、 新增標籤分類.............................................................................................................

2.2、 刪除分類標籤.............................................................................................................

2.3、 更新分類標籤...........................................................................................................

1、 引言

1.1、 REST 介紹

REpresentational State Transfer (REST) 是一種架構原則，其中將 web 服務視為資源，可以由其 URL 唯一標識。RESTful Web 服務的關鍵特點是明確使用 HTTP 方法來表示不同的操作的呼叫。

REST 的基本設計原則對典型 CRUD 操作使用 HTTP 協議方法：

POST - 建立資源

GET - 檢索資源

PUT – 更新資源

DELETE - 刪除資源

REST 服務的主要優勢在於：

它們是跨平臺 (Java、.net、PHP 等）高度可重用的，因為它們都依賴基本 HTTP 協議。

它們使用基本的 XML，而不是複雜的 SOAP XML，使用非常方便。

基於 REST 的 web 服務日益成為後端企業服務整合的首選方法。與基於 SOAP 的web 服務相比，它的程式設計模型簡單，而本機 XML（而不是 SOAP ）的使用減少了序列化和反序列化過程的複雜性，並且不再需要其他作用相同的第三方庫。

1.2、 編寫目的

編寫本文的目的是為了將系統功能進行模組化、服務化，將使用者的操作以服務的方式提供。系統與系統之間遵循服務規範，將系統與系統之間的互動轉為定製化服務互動，以實現系統與系統之間的整合。

1.3、 編寫原則

可定址性（Addressability）REST 中的所有東西都基於資源 的概念。資源與 OOP 中的物件或其他名詞不同，它是一種抽象，必須可以透過 URI 定址或訪問。介面一致性（Interface uniformity）與 SOAP 或其他標準不同，REST 要求用來操縱資源的

方法或動詞不是任意的。這意味著 RESTful 服務的開發人員只能使用 HTTP 支援的方法，比如GET、PUT、POST、DELETE 等等。因此不需要使用 WSDL 等服務描述語言。無狀態（Statelessness）為了增強可伸縮性，伺服器端不儲存客戶機的狀態資訊。這使伺服器不與特定的客戶機相繫結，負載平衡變得簡單多了。這還讓伺服器更容易監視、更可靠。

具象（Representational）客戶機總是與資源的某種具象互動，絕不會直接與資源本身互動。

同一資源還可以有多個具象。理論上說，持有資源的具象的任何客戶機應該有操縱底層資源的足夠資訊。

連通性（Connectedness）任何基於 REST 的系統都應該預見到客戶機需要訪問相關的資源，應該在返回的資源具象中包含這些資源。例如，可以以超連結的形式包含特定 RESTful 服務的操作序列中的相關步驟，讓客戶機可以根據需要訪問它們。

1.4、 變更歷史

2、 服務使用說明

2.1、 當前系統已經提供的服務

2.2、 GET 方式呼叫服務

說明：

1. 請求方式包括：GET (這裡以 area 服務為例項，GET 對應每一個服務 Resource 中的

@RequestMapping(value = "treeData", method = RequestMethod.GET))

2. 請求 URL：rest 服務請求地址,對應 XXXServiceResource.java 的 mapping 配置中的 value

@RequestMapping(value = "treeData", method = RequestMethod.GET))

3. 其中 GET 請求只包含了請求方式和請求的 URL，返回的結果以 json 格式返回給客戶端

2.3、 POST、DELETE、UPDATE 方式呼叫服務

說明：

1. 請求方式選擇 POST、DELETE、UPDATE(這裡以儲存收藏功能為例（PUT 請求），對應每一個服 Resource 中的@RequestMapping(value = "save", method = RequestMethod.PUT))

2. Json 引數： 其中 POST、DELETE、UPDATE 可能傳遞引數透過 json，也可能透過路徑直接拼接引數，這邊以傳遞 json 到服務端為例項，對應服務端程式碼：

public JSONObject save(@RequestBody JSONObject obj, BookmarkTag bookmarkTag) {

3. 請求 URL：rest 服務請求地址,對應 XXXServiceResource.java 的 mapping 配置中的 value@RequestMapping(value = " save", method = RequestMethod.PUT))

4. 返回的結果以 json 格式返回給客戶端

3、 服務列表（這邊以我的收藏服務為例）

3.1、 新增標籤分類

3.2、 刪除分類標籤

3.3、 更新分類標籤

3.4、 獲取分類標籤列表