JEESZ REST服務(wù)接口文檔

目    錄

• 1、     引言..........................................................................................................
• 1.1、  REST介紹................................................................................................
• 1.2、  編寫目的…………………………………………………………………………...
• 1.3、  編寫原則..................................................................................................
• 1.4、  變更歷史..................................................................................................
• 2、     服務(wù)使用說明
•  2.1、 當(dāng)前系統(tǒng)已經(jīng)提供的服務(wù)…………………………………………………....
•  2.2、 GET方式調(diào)用服務(wù)………………………………………………………………
•  2.3、  POST方式調(diào)用服務(wù)…………………………………………………………...
• 3、      我的收藏服務(wù)列表................................................................................
• 3.1、   添加標(biāo)簽分類.........................................................................................
• 3.2、   刪除分類標(biāo)簽........................................................................................
• 3.3、   更新分類標(biāo)簽........................................................................................

1、            引言

1.1、   REST介紹

REpresentational State Transfer (REST) 是一種架構(gòu)原則，其中將 web 服務(wù)視為資源，可以由其 URL 唯一標(biāo)識(shí)。RESTful Web 服務(wù)的關(guān)鍵特點(diǎn)是明確使用 HTTP 方法來表示不同的操作的調(diào)用。

REST 的基本設(shè)計(jì)原則對(duì)典型 CRUD 操作使用 HTTP 協(xié)議方法：

POST - 創(chuàng)建資源

GET - 檢索資源

PUT – 更新資源

DELETE - 刪除資源

REST 服務(wù)的主要優(yōu)勢(shì)在于：

它們是跨平臺(tái) (Java、.net、PHP 等）高度可重用的，因?yàn)樗鼈兌家蕾嚮?HTTP 協(xié)議。

它們使用基本的 XML，而不是復(fù)雜的 SOAP XML，使用非常方便。

基于 REST 的 web 服務(wù)日益成為后端企業(yè)服務(wù)集成的首選方法。與基于 SOAP 的 web 服務(wù)相比，它的編程模型簡(jiǎn)單，而本機(jī) XML（而不是 SOAP ）的使用減少了序列化和反序列化過程的復(fù)雜性，并且不再需要其他作用相同的第三方庫(kù)。

1.2、   編寫目的

編寫本文的目的是為了將系統(tǒng)功能進(jìn)行模塊化、服務(wù)化，將用戶的操作以服務(wù)的方式提供。系統(tǒng)與系統(tǒng)之間遵循服務(wù)規(guī)范，將系統(tǒng)與系統(tǒng)之間的交互轉(zhuǎn)為定制化服務(wù)交互，以實(shí)現(xiàn)系統(tǒng)與系統(tǒng)之間的集成。

1.3、   編寫原則

可尋址性（Addressability）REST 中的所有東西都基于資源 的概念。資源與 OOP 中的對(duì)象或其他名詞不同，它是一種抽象，必須可以通過 URI 尋址或訪問。

接口一致性（Interface uniformity）與 SOAP 或其他標(biāo)準(zhǔn)不同，REST 要求用來操縱資源的方法或動(dòng)詞不是任意的。這意味著 RESTful 服務(wù)的開發(fā)人員只能使用 HTTP 支持的方法，比如 GET、PUT、POST、DELETE 等等。因此不需要使用 WSDL 等服務(wù)描述語言。

無狀態(tài)（Statelessness）為了增強(qiáng)可伸縮性，服務(wù)器端不存儲(chǔ)客戶機(jī)的狀態(tài)信息。這使服務(wù)器不與特定的客戶機(jī)相綁定，負(fù)載平衡變得簡(jiǎn)單多了。這還讓服務(wù)器更容易監(jiān)視、更可靠。

具象（Representational）客戶機(jī)總是與資源的某種具象交互，絕不會(huì)直接與資源本身交互。同一資源還可以有多個(gè)具象。理論上說，持有資源的具象的任何客戶機(jī)應(yīng)該有操縱底層資源的足夠信息。

連通性（Connectedness）任何基于 REST 的系統(tǒng)都應(yīng)該預(yù)見到客戶機(jī)需要訪問相關(guān)的資源，應(yīng)該在返回的資源具象中包含這些資源。例如，可以以超鏈接的形式包含特定 RESTful 服務(wù)的操作序列中的相關(guān)步驟，讓客戶機(jī)可以根據(jù)需要訪問它們。基于 REST 的 Web 服務(wù)日益成為后端企業(yè)服務(wù)集成的

1.4、   變更歷史

2、      服務(wù)使用說明

2.1、 當(dāng)前系統(tǒng)已經(jīng)提供的服務(wù)

2.2、 GET方式調(diào)用服務(wù)

說明：

1.       請(qǐng)求方式包括：GET (這里以area服務(wù)為實(shí)例，GET對(duì)應(yīng)每一個(gè)服務(wù)Resource中的@RequestMapping(value = "treeData", method = RequestMethod.GET))

2.       請(qǐng)求URL：rest服務(wù)請(qǐng)求地址,對(duì)應(yīng)XXXServiceResource.java的mapping配置中的value

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

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

2.3、 POST、DELETE、UPDATE方式調(diào)用服務(wù)

說明：

1.       請(qǐng)求方式選擇POST、DELETE、UPDATE(這里以保存收藏功能為例（PUT請(qǐng)求），對(duì)應(yīng)每一個(gè)服Resource中的@RequestMapping(value = "save", method = RequestMethod.PUT))

2.       Json參數(shù)： 其中POST、DELETE、UPDATE可能傳遞參數(shù)通過json，也可能通過路徑直接拼接參數(shù)，這邊以傳遞json到服務(wù)端為實(shí)例，對(duì)應(yīng)服務(wù)端代碼：

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

3.       請(qǐng)求URL：rest服務(wù)請(qǐng)求地址,對(duì)應(yīng)XXXServiceResource.java的mapping配置中的value

@RequestMapping(value = " save", method = RequestMethod.PUT))

4.       返回的結(jié)果以json格式返回給客戶端

3、      服務(wù)列表（這邊以我的收藏服務(wù)為例)

3.1、 添加標(biāo)簽分類

3.2、 刪除分類標(biāo)簽

3.3、 更新分類標(biāo)簽

3.4、 獲取分類標(biāo)簽列表

想了解更多詳細(xì)請(qǐng)點(diǎn)擊源碼地址獲取：mingli

有興趣的朋友們可以前往球球哦~一起分享學(xué)習(xí)技術(shù)：2042849237