什么是REST API

1. 什么是RESTful API

REST API，全称 Representational State Transfer，最初由计算机科学家 Roy Fielding 提出。
是遵循 REST 架构规范的应用编程接口（API），支持与 RESTful Web 服务进行交互。

又被称作 RESTful API，充满Representational State Transfer的API

2. REST API设计规范

2.1 设计规范

• 将一切数据视作资源
• 利用HTTP请求方式，描述对资源的操作 (增/删/改/查)
• 通过HTTP响应状态码，描述对资源的操作结果 (如 : 200/5xx)

2.2 期望效果

• 看URL知道是什么资源
• 看Method知道要对资源进行什么操作
• 看Response Code知道操作是否成功

2.3 Method规范 : 用于描述操作 (动词)

• GET : 用于读取资源
• POST : 用于创建资源
• PUT : 用于更新资源 (客户端提供更新后的完整资源)
• PATCH: 用于局部更新 (客户端提供资源局部变量)
• DELETE : 用于删除资源

2.4 URL规范 : 只使用名词，不能有动词

基于HTTP协议URL对外暴露

• 标准格式
  • http(s)://域名:端口[/版本]/资源1[1子资源21.../子资源n][/路径变量)
• 多版本控制
  • GET http(s)://edu.51cto.com/v1.1/blog/article/10
• 数据查询采用复数
  • GET http(s)://edu.51cto.com/v1.1/blog/articles?categoryld=10
• 反面典型
  • GET http(s)://edu.51cto.com/article/select by id?id=10

2.5 Response规范 : 需保持统一结构

{
	code : //描述状态
	data : 返回数据
	message : //状态描述
}

可以定义自己的结构，对所有接口的返回结构保持统一就行

2.6 有什么好处

易于理解和实现，支持跨平台和跨语言通信，灵活、扩展性强，使用标准HTTP协议，简化数据交换。
支持多种数据格式，易于缓存和分层架构，提升了应用的开发效率和性能。

2.7 接口设计注意事项

• 接口要保证幂等性设计
• 标准化的相应结果集
• 接口设计采用无状态方案
  • Restful接口每一个请求访问进来应都能得到相同的预期

3. 接口幂等性设计

幂等性 : 当多次重复请求时，接口能够保证与预期相符的结果

例如 : 我们设计了一个为员工涨薪的接口，本次请求发送后为1号员工涨薪500元。

PUT https://edu.lagou.com/employee/salaary
{"id":"1","incr_salary":500}

3.1 如果你是一个新人没有考虑幂等性特性

可能会这么写，伪代码如下 :

//查询1号员工数据
Employee employee = employeeService.selectById(1);  
//更新工资
employee.setSalary(employee.getSalary() + incrSalary);
//执行更新语句
employeeService.update(employee)

对于这段代码，单独运行是没有任何问题的，但是我们要注意 :

在分布式环境下，为了保证消息的高可靠性，往往客户端会采用重试或消息补偿的形式重复发送同一个请求，那么这种情况下这段代码就会出严重问题，每一个重复请求被发送到服务器会让该员工工资增加500，最终该员工工资会大于要求实际应收工资。

3.2 幂等解决方案 : 乐观锁设计

在行业中有一种乐观锁设计，在工资表额外增加一个version字段，代表当前数据的版本，任何对该数据修改操作都会让version字段值+1，这个version数值要求附加在请求中。

PUT https://edu.lagou.com/employee/salaary
{"id":"1","incr_salary":500,"version":1}

数据库

id	salary	version
1	3000	1

相应的，服务器代码也要做出相应变化

//查询1号员工数据
Employee employee = employeeService.selectById(1);  
//更新工资
employee.setSalary(employee.getSalary() + incrSalary);
//设置版本号
employee.setVersion(employee.getVersion() + 1);
//执行更新语句
employeeService.update(employee)

注意此时update方法除了条件id外，还要增加version的判断，如下所示 :

update employee set salary = 3500,version=2 where id=1 and version=1

当执行成功后，1号员工数据库将工资更新未3500，版本为2

id	salary	version
1	3500	2

3.3 如何保证幂等呢 ?

假设客户端再次发送重复的请求

PUT https://edu.lagou.com/employee/salaary
{"id":"1","incr_salary":500,"version":1}

后台逻辑仍然会执行下面的update语句

update employee set salary = 3500,version=2 where id=1 and version=1

此时，因为数据库中version字段已经更新未2，where筛选条件将无法得到任何数据，自然就不会产生实质的更新操作，我们幂等性的初衷就已经达到了。

4. 参考

什么是 REST API 一文读懂 (RESTful API)
【IT老齐170】如何优雅的设计RESTful API接口
REST API 简介 - RESTful Web 服务 (apifox.com)
【前端面试】当被面试官问到什么是 RESTFul-API_哔哩哔哩_bilibili

Postman中的REST API 示例 : Postman REST API basics: CRUD, test & variable