RESTful API 规范

Representational State Transfer(REST), 表现层状态转化. 如果一个架构符合REST原则，就称它为RESTful架构。

概念

REST的名称"表现层状态转化"中，省略了主语。"表现层"其实指的是"资源"（Resources）的"表现层"。所谓"资源"，就是网络上的一个实体，或者说是网络上的一个具体信息。它可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实在。
你可以用一个URI（统一资源定位符）指向它，每种资源对应一个特定的URI。要获取这个资源，访问它的URI就可以，因此URI就成了每一个资源的地址或独一无二的识别符。所谓"上网"，就是与互联网上一系列的"资源"互动，调用它的URI。

表现层（Representation）

"资源"是一种信息实体，它可以有多种外在表现形式。我们把"资源"具体呈现出来的形式，叫做它的表现层（Representation）。

URI只代表资源的实体，不代表它的形式。严格地说，有些网址最后的".html"后缀名是不必要的，因为这个后缀名表示格式，属于"表现层"范畴，而URI应该只代表"资源"的位置。
它的具体表现形式，应该在HTTP请求的头信息中用Accept和Content-Type字段指定，这两个字段才是对"表现层"的描述。

状态转化（State Transfer）

互联网通信协议HTTP协议，是一个无状态协议。这意味着，所有的状态都保存在服务器端。因此，如果客户端想要操作服务器，必须通过某种手段，让服务器端发生"状态转化"（State Transfer）。而这种转化是建立在表现层之上的，所以就是"表现层状态转化"。
客户端用到的手段，只能是HTTP协议。具体来说，就是HTTP协议里面，四个表示操作方式的动词：GET、POST、PUT、DELETE。
它们分别对应四种基本操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源。

综述

每一个URI代表一种资源；
客户端和服务器之间，传递这种资源的某种表现层；
客户端通过四个HTTP动词，对服务器端资源进行操作，实现"表现层状态转化"。

注意事项:
最常见的一种设计错误，就是URI包含动词。因为"资源"表示一种实体，所以应该是名词，URI不应该有动词，动词应该放在HTTP协议中。
另一个设计误区，就是在URI中加入版本号. 因为不同的版本，可以理解成同一种资源的不同表现形式，所以应该采用同一个URI。版本号可以在HTTP请求头信息的Accept字段中进行区分

但是, 将版本号放在HTTP头信息中不够直观, 不如放到URL中方便. Github 采用这种做法。

设计

协议: 使用HTTPS协议.
域名: 部署到专用域名之下. 例如: https://yujian95.cn/api/
版本（Versioning）: 将API版本号放入URL. 例如: https://yujian95.cn/api/v1/ 或 https://api.yujian95.cn/v1/
路径（Endpoint）: 路径又称"终点"（endpoint），表示API的具体网址。在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。
HTTP动词: 对于资源的具体操作类型，由HTTP动词表示。
- GET（SELECT）：从服务器取出资源（一项或多项）。
- POST（CREATE）：在服务器新建一个资源。
- PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
- PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
- DELETE（DELETE）：从服务器删除资源。
- HEAD：获取资源的元数据。
- OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。
过滤（Filtering）: API应该提供参数，过滤返回结果。参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。
- ?limit=10：指定返回记录的数量
- ?offset=10：指定返回记录的开始位置。
- ?page=2&per_page=100：指定第几页，以及每页的记录数。
- ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
- ?animal_type_id=1：指定筛选条件
状态码（Status Codes）: 服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。
- 查看完整 Http 状态码
- 200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
- 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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
错误处理（Error handling）: 如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。
```
  {
    "error": "Invalid API key"
  }
```
返回结果: 针对不同操作，服务器向用户返回的结果应该符合以下规范。
- GET /collection：返回资源对象的列表（数组）
- GET /collection/resource：返回单个资源对象
- POST /collection：返回新生成的资源对象
- PUT /collection/resource：返回完整的资源对象
- PATCH /collection/resource：返回完整的资源对象
- DELETE /collection/resource：返回一个空文档
Hypermedia API: 即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。例如,向api.example.com的根目录发送请求,就会得到这样一个文档. Hypermedia API的设计被称为HATEOAS。
- link属性，用户读取这个属性就知道下一步该调用什么API了。
- rel表示这个API与当前网址的关系（collection关系，并给出该collection的网址）。
- href表示API的路径。
- title表示API的标题。
- type表示返回类型。
```
{"link": 
  {
  "rel":   "collection https://www.example.com/zoos",
  "href":  "https://api.example.com/zoos",
  "title": "List of zoos",
  "type":  "application/vnd.yourformat+json"
  }
}
```
其他: API的身份认证应该使用OAuth 2.0框架。服务器返回的数据格式，应该尽量使用JSON，避免使用XML。

实践

/**
 * @file: GroupController
 * @author: <a href="https://yujian95.cn/about/">YuJian</a>
 * @description: 分组管理模块
 * @date: Created in 10/12/19  2:12 PM
 * @modified:
 * @version: 1.0
 */

@Api(value = "/user", tags = "分组管理模块")
@RestController
@RequestMapping("/user")
@CrossOrigin
public class UserGroupController {

    @Resource
    private IUserGroupService groupService;

    @Resource
    private IAdminService adminService;

    @Resource
    private IUserBasicInfoService infoService;

    @ApiOperation("添加分组")
    @RequestMapping(value = "/group", method = RequestMethod.POST)
    public CommonResultDTO createGroup(@RequestBody GroupParam param) {

        if (groupService.insert(param)) {
            return CommonResultDTO.success();
        }

        return CommonResultDTO.failed();
    }

    @ApiOperation("删除分组")
    @RequestMapping(value = "/group/{groupId}", method = RequestMethod.DELETE)
    public CommonResultDTO deleteGroup(@PathVariable Integer groupId) {
        if (groupService.count(groupId) == 0) {
            return CommonResultDTO.validateFailed();
        }

        if (groupService.delete(groupId)) {
            // 删除,同时修改原有成员分组
            return CommonResultDTO.success();
        }

        return CommonResultDTO.failed();
    }

    @ApiOperation("编辑分组")
    @RequestMapping(value = "/group/{groupId}", method = RequestMethod.PUT)
    public CommonResultDTO updateGroup(@PathVariable Integer groupId, @RequestBody GroupParam param) {
        if (groupService.count(groupId) == 0) {
            return CommonResultDTO.validateFailed();
        }

        if (groupService.update(groupId, param)) {
            return CommonResultDTO.success();
        }

        return CommonResultDTO.failed();
    }

    @ApiOperation("获取分组信息")
    @RequestMapping(value = "/group/{groupId}", method = RequestMethod.GET)
    public CommonResultDTO getGroup(@PathVariable Integer groupId) {
        if (groupService.count(groupId) == 0) {
            return CommonResultDTO.validateFailed();
        }

        TbUserGroup group = groupService.get(groupId);

        if (group == null) {
            return CommonResultDTO.failed();
        }

        return CommonResultDTO.success(group);
    }

    @ApiOperation("分页: 查找分组信息")
    @RequestMapping(value = "/group/list/{pageNum}/{pageSize}", method = RequestMethod.GET)
    public CommonResultDTO searchGroup(@PathVariable Integer pageNum, @PathVariable Integer pageSize,
                                       @RequestParam Integer status, @RequestParam(required = false) String keyWord) {
        if (status > 1 || status < -1) {
            return CommonResultDTO.validateFailed();
        }

        return CommonResultDTO.success(CommonPageDTO.restPage(groupService.list(keyWord, status, pageNum, pageSize)));
    }

    @ApiOperation("设置状态")
    @RequestMapping(value = "/list/status", method = RequestMethod.PUT)
    public CommonResultDTO updateGroupStatus(@RequestParam Integer status, @RequestParam List<Integer> list) {
        if (list.size() == 0 || status > 1 || status < -1) {
            return CommonResultDTO.validateFailed();
        }

        return CommonResultDTO.success(groupService.updateStatus(status, list));
    }
}

RESTful API 规范

RESTful API 规范

概念

设计

实践

参见

评论

RESTful API 规范

RESTful API 规范

概念

设计

实践

参见

推荐阅读

常见计划排程算法

PF4J：轻量级 Java 插件框架：轻量级 Java 插件框架

Groovy 使用指南

CloudOps：云运维

评论