RESTful風格設計API介面
概述
-
REST(Resource Representational State Transfer):表現層狀態轉化 REST就是一種框架理論,或者說一種設計風格,是一組架構約束條件和 原則。滿足這些約束條件和原則的應用程式或設計就是 RESTful,REST的規定,資源的表現與資源的狀態轉化不能體現在URI上面
-
RESTful架構: 每一個URI代表一種資源; 客戶端和伺服器之間,傳遞這種資源的某種表現層; 客戶端通過HTTP提供的統一介面,對伺服器端資源進行操作,實現"表現層(使用HTTP動詞去促使伺服器端資源的)狀態轉化"。
-
Http方法: GET/POST/PUT/DELETE/PATCH/HEAD/OPTIONS
RESTful設計
- URI(資源路徑設計): 在RESTful架構中,每個網址代表一種資源(resource),所以網址中不能有動詞,只能有名詞,而且所用的名詞往往與資料庫的表格名對應。
https://api.xxx.com/employees:員工資源
https://api.xxx.com/departments:部門資源
- 動作設計 GET:從伺服器取出資源(一項或多項)。 POST:在伺服器新建一個資源。 PUT:在伺服器更新資源(客戶端提供改變後的完整資源)。 PATCH:在伺服器更新資源(客戶端提供改變的屬性【補丁】)。 DELETE:從伺服器刪除資源。 HEAD:獲得一個資源的元資料,比如一個資源的hash值或者最後修改日期; OPTIONS:獲得客戶針對一個資源能夠實施的操作;
GET /employees:列出所有員工
POST /employees:新建一個員工
GET /employees/ID:獲取某個指定員工的資訊
PUT /employees/ID:更新某個指定員工的資訊(提供該動物園的全部資訊)
PATCH /employees/ID:更新某個指定員工的資訊(提供該動物園的部分資訊)
DELETE /employees/ID:刪除某個員工
GET /departments/ID/employees:列出某個指定部門的所有員工
DELETE /departments/ID/employees/ID:刪除某個指定部門的指定員工
實戰
/** * 新增操作 * 方法: POST * 設計路徑:/api/employees */ @RequestMapping(value = "/employee/add", method = RequestMethod.POST) @ResponseBody public JSONResultVo addEmployee(Employee employee){ JSONResultVo resultVo = new JSONResultVo(); try { employeeService.addEmployee(employee); } catch (VisibleException e) { resultVo.setErrorMsg(e.getMessage()); e.printStackTrace(); } catch (Exception e) { resultVo.setErrorMsg(e.getMessage()); e.printStackTrace(); } return resultVo; }
/**
* 刪除操作
* 方法:DELETE
* 設計路徑:/api/employees
*/
@RequestMapping(value = "/employee/delete", method = RequestMethod.DELETE)
@ResponseBody
public JSONResultVo deleteEmployee(Long id){
JSONResultVo resultVo = new JSONResultVo();
try {
employeeService.deleteEmployee(id);
} catch (VisibleException e) {
resultVo.setErrorMsg(e.getMessage());
e.printStackTrace();
} catch (Exception e) {
resultVo.setErrorMsg(e.getMessage());
e.printStackTrace();
}
return resultVo;
}
/**
* 更改操作
* 方法:PATCH
* 設計路徑:/api/employees
*/
@RequestMapping(value = "/employee/update", method = RequestMethod.PATCH )
@ResponseBody
public JSONResultVo updateEmployee(Employee employee){
JSONResultVo resultVo = new JSONResultVo();
try {
employeeService.updateEmployee(id);
} catch (VisibleException e) {
resultVo.setErrorMsg(e.getMessage());
e.printStackTrace();
} catch (Exception e) {
resultVo.setErrorMsg(e.getMessage());
e.printStackTrace();
}
return resultVo;
}
/**
* 查詢操作
* 方法:GET
* 設計路徑:/api/employees/{id}
*/
@RequestMapping(value = "/employee/update", method = RequestMethod.PATCH )
@ResponseBody
public JSONResultVo updateEmployee(@PathVariable(“id”) Long id){
JSONResultVo resultVo = new JSONResultVo();
try {
Employee employee = employeeService.selectById(id);
resultVo.setResult(employee);
} catch (VisibleException e) {
resultVo.setErrorMsg(e.getMessage());
e.printStackTrace();
} catch (Exception e) {
resultVo.setErrorMsg(e.getMessage());
e.printStackTrace();
}
return resultVo;
}
常見狀態碼
200 OK - [GET]:伺服器成功返回使用者請求的資料。 201 CREATED - [POST/PUT/PATCH]:使用者新建或修改資料成功。 202 Accepted - []:表示一個請求已經進入後臺排隊(非同步任務) 204 NO CONTENT - [DELETE]:使用者刪除資料成功。 400 INVALID REQUEST - [POST/PUT/PATCH]:使用者發出的請求有錯誤,伺服器沒有進行新建或修改資料的操作,該操作是冪等的。 401 Unauthorized - []:表示使用者沒有許可權(令牌、使用者名稱、密碼錯誤)。 403 Forbidden - [] 表示使用者得到授權(與401錯誤相對),但是訪問是被禁止的。 404 NOT FOUND - []:使用者發出的請求針對的是不存在的記錄,伺服器沒有進行操作,該操作是冪等的。 406 Not Acceptable - [GET]:使用者請求的格式不可得(比如使用者請求JSON格式,但是隻有XML格式)。 410 Gone -[GET]:使用者請求的資源被永久刪除,且不會再得到的。 422 Unprocesable entity - [POST/PUT/PATCH] 當建立一個物件時,發生一個驗證錯誤。 500 INTERNAL SERVER ERROR - [*]:伺服器發生錯誤,使用者將無法判斷髮出的請求是否成功。