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 规范

概念

设计

实践

参见

推荐阅读

语义化版本规范

SQL 练习题

学习路径 - Java学习的正确打开方式

评论