什么是API

API（Application Programming Interface）：应用程序编程接口。

  • 在进行后端开发的时候，主要的工作就是为前端或者其他后端服务提供 API
  • API 不仅仅代表后端系统暴露的接口，像框架中提供的方法也属于 API 的范畴。

REST简介

REST 是 REpresentational State Transfer 的缩写。这个词组的翻译过来就是“表现层状态转化”。
REST:访问资源地址的一种格式

REST风格优点

  • 隐藏资源的访问行为，无法通过地址得知资源是何种操作
  • 简化访问资源地址书写

RESTful 架构

  • 每一个 URI 代表一种资源；
  • 客户端和服务器之间，以某种表现形式比如 json，xml，image,txt 等等传递某种资源；
  • 客户端通过特定的 HTTP 动词，对服务器端资源进行操作，实现”表现层状态转化”。

RestFul入门案例

步骤：

  1. 设定http请求动作(动词)
  2. 设定请求参数(路径变量)
  3. 访问资源地址(使用http访问工具)

示范案例

  1. @RestController
  2. @RequestMapping("/books")
  3. public class BookController {
  4.     // 添加书籍
  5.     @PostMapping
  6.     public String save(@RequestBody Book book) {
  7.         return "book save...";
  8.     }
  10.     // 修改
  11.     @PutMapping
  12.     public String update(@RequestBody Book book) {
  13.         return "book update....";
  14.     }
  16.     // 删除
  17.     @DeleteMapping("/{id}")
  18.     public String delete(@PathVariable Integer id) {
  19.         return "book delete...,id:" + id;
  20.     }
  22.     // 查询所有
  23.     @GetMapping
  24.     public String getBooks() {
  25.         return "book getBooks";
  26.     }
  28.     // 根据id查询
  29.     @GetMapping("/{id}")
  30.     public String getBookById() {
  31.         return "book getBookById";
  32.     }
  • postman：添加书籍示范

image.png


RESTful API 规范

动作

  • GET：请求从服务器获取特定资源。举个例子：GET /books（获取所有书籍）
  • POST：在服务器上创建一个新的资源。举个例子：POST /books（添加书籍）
  • PUT：更新服务器上的资源（客户端提供更新后的整个资源）。举个例子：PUT /books/12（更新编号为0588的书籍信息）
  • DELETE：从服务器删除特定的资源。举个例子：DELETE /books/12（删除编号为 0588的书籍）
  • PATCH：更新服务器上的资源（客户端提供更改的属性，可以看做作是部分更新）

路径（接口命名）

路径又称”终点”（endpoint），表示 API 的具体网址。
常见的路径规范：

  • 网址中不能有动词，只能有名词，API 中的名词也应该使用复数。 因为 REST 中的资源往往和数据库中的表对应，而数据库中的表都是同种记录的”集合”（collection）。如果 API 调用并不涉及资源（如计算，翻译等操作）的话，可以用动词。比如：GET /calculate?param1=11&param2=33 。
  • 不用大写字母，建议用中杠 - 不用下杠 _ 。比如邀请码写成 invitation-code而不是 invitation_code 。
  • 善用版本化 API。当我们的 API 发生了重大改变而不兼容前期版本的时候，我们可以通过 URL 来实现版本化，比如 http://api.example.com/v1、http://apiv1.example.com 。版本不必非要是数字，只是数字用的最多，日期、季节都可以作为版本标识符，项目团队达成共识就可。
  • 接口尽量使用名词，避免使用动词。 RESTful API 操作（HTTP Method）的是资源（名词）而不是动作（动词）。 ``` GET /classes：列出所有班级 POST /classes：新建一个班级 GET /classes/{classId}：获取某个指定班级的信息 PUT /classes/{classId}：更新某个指定班级的信息（一般倾向整体更新） PATCH /classes/{classId}：更新某个指定班级的信息（一般倾向部分更新） DELETE /classes/{classId}：删除某个班级 GET /classes/{classId}/teachers：列出某个指定班级的所有老师的信息 GET /classes/{classId}/students：列出某个指定班级的所有学生的信息 DELETE /classes/{classId}/teachers/{ID}：删除某个指定班级下的指定的老师的信息
  2. <a name="PnwNP"></a>
  3. #### 过滤信息（Filtering）
  4. 查询的时候需要添加特定条件的话，建议使用 url 参数的形式。比如我们要查询 state 状态为 active 并且 name 为 guidegege 的班级：

GET /classes?state=active&name=guidegege

```

状态码（Status Codes）

image.png

参考文献