RESTful API资料整理

基础

REST 简介

本质：一种软件架构风格
核心：面向资源设计的API
解决问题：

• 降低开发的复杂性
• 提高系统的可伸缩性

设计概念和准则：

• 网络上的所有事物都可以被抽象为资源
• 每一个资源都有唯一的资源标识，对资源的操作不会改变这些标识
  所有的操作都是无状态的（本次操作、下次操作、上次操作之间无关系）

资源：网络上的一个实体、具体信息。

REST 是英文 Representational State Transfer 的缩写，是近年来迅速兴起的，一种基于 HTTP，URI，以及 XML 这些现有协议与标准的，针对网络应用的设计和开发方式。它可以降低开发的复杂度，提高系统的可伸缩性。

REST 的核心是可编辑的资源及其集合，REST 的基本概念和原则包括：系统上的所有事物都被抽象为资源；每个资源对应唯一的资源标识；对资源的操作不会改变资源标识本身；所有的操作都是无状态的；等等。

RESTful架构：

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

URI

URI 表示资源，资源一般对应服务器端领域模型中的实体类。

HTTP动词

对于资源的具体操作类型，由HTTP动词表示。
常用的HTTP动词有下面五个（括号里是对应的SQL命令）。

• GET（SELECT）：从服务器取出资源（一项或多项）
• POST（CREATE）：在服务器新建一个资源。
• PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
• PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
• DELETE（DELETE）：从服务器删除资源。

还有两个不常用的HTTP动词。

• HEAD：获取资源的元数据。
• OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

示例：

• GET /zoos：列出所有动物园
• POST /zoos：新建一个动物园
• GET /zoos/ID：获取某个指定动物园的信息
• PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
• PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
• DELETE /zoos/ID：删除某个动物园
• GET /zoos/ID/animals：列出某个指定动物园的所有动物
• DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

过滤信息

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

下面是一些常见的参数。

• ?limit=10：指定返回记录的数量
• ?offset=10：指定返回记录的开始位置。
• ?page=2&per_page=100：指定第几页，以及每页的记录数。
• ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
• ?animal_type_id=1：指定筛选条件

状态码

服务器向用户返回的状态码和提示信息

• 1xx：相关信息
• 2xx：操作成功
• 3xx：重定向
• 4xx：客户端错误
• 5xx：服务器错误

全部状态码链接

错误处理

如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。

{
    error: "Invalid API key"
}

返回结果

针对不同操作，服务器向用户返回的结果应该符合以下规范。

• GET /collection：返回资源对象的列表（数组）
• GET /collection/resource：返回单个资源对象
• POST /collection：返回新生成的资源对象
• PUT /collection/resource：返回完整的资源对象
• PATCH /collection/resource：返回完整的资源对象
• DELETE /collection/resource：返回一个空文档

不要返回纯本文，应该是一个 JSON 对象，返回标准的结构化数据。所以服务器回应的 HTTP 头的Content-Type属性要设为application/json。

发生错误时，不要返回 200 状态码，正确的做法是，状态码反映发生的错误，具体的错误信息放在数据体里面返回

其他

• 身份认证可以使用OAuth 2.0框架
• 服务器返回的数据格式，应该尽量使用JSON

设计规范

• 用名词代替动词表示资源

GET /employees
GET /employees?state=external
POST /employees
PUT /employees/56

• 用HTTP方法操作资源
  URL指定资源，HTTP动词来指定如何处理资源。
• 推荐用复数名词
  事实上这是个人爱好问题，但复数形式更为常见

/employees
/employees/21

• 常用5类接口

  
  屏幕快照 2020-03-25 下午10.22.58.png

• 常用状态码

  
  屏幕快照 2020-03-25 下午10.23.05.png

基本规范

• 使用”/“表示层级关系
• url 不能以”/“结尾
• url 中不能包含空格
• 不要再url中添加CRUD

Demo

@RestController
@RequestMapping("/v1/users")
public class UserController {

    @GetMapping("/")
    public ResponseEntity<User> list() {
        return null;
    }

    @GetMapping("/{id}")
    public User query(@PathVariable("id") String id) {
        return null;
    }

    @PostMapping("/")
    public ResponseEntity<User> create(@RequestBody User user) {
        return null;
    }

    @PutMapping("/{id}")
    public ResponseEntity<User> update(@PathVariable("id") String id, @RequestBody User user) {
        return null;
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<User> delete(@PathVariable("id") String id) {
        return null;
    }

    @PostMapping("/batch_create")
    public ResponseEntity<User> batchCreate(@RequestBody List<User> users) {
        return null;
    }

    @PostMapping("/batch_delete")
    public ResponseEntity<User> batchDelete(@RequestBody List<User> users) {
        return null;
    }

    @PostMapping("/age")
    public ResponseEntity<User> updateAge(@RequestParam("value") Integer age) {
        return null;
    }

    @PostMapping("/{:id}/undelete")
    public ResponseEntity<User> undelete(@PathVariable("id") String id) {
        return null;
    }

    @PostMapping("/check")
    public ResponseEntity<User> checkName(@RequestParam("name") String name) {
        return null;
    }

    @GetMapping("/{:id}/age")
    public ResponseEntity<User> queryAge(@PathVariable("id") String id) {
        return null;
    }

    @GetMapping("/{:id}/name")
    public ResponseEntity<User> queryByUserIdAndName(@PathVariable("id") String id, @RequestParam("name") String name) {
        return null;
    }

    @GetMapping("/{:id}/projects/count")
    public ResponseEntity<User> countProjects(@PathVariable("id") String id, @RequestParam("name") String name) {
        return null;
    }

    @GetMapping("/")
    public ResponseEntity<User> listByOptions(@RequestBody Map<String, Object> options) {
        return null;
    }

}

参考资料

阮一峰 RESTful API 设计指南
阮一峰 RESTful API 最佳实践
微软RESTful API设计指南
书籍 Web API Design
Testing RESTful Services in Java: Best Practices
choerodon RESTful Api 规范