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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。