简介

RESTful API 是应用程序接口 (API) 的一种架构风格，它使用 HTTP 请求来访问和使用数据。该数据可用于 GET、PUT、POST 和 DELETE 数据类型，这些数据类型是指有关资源的操作的读取、更新、创建和删除。

RESTful API（也称为 RESTful Web 服务或 REST API）基于表示状态传输 (REST)，它是一种架构风格和经常用于 Web 服务开发的通信方法。

总结：Restful API就是一种架构风格，对API如何使用进行一些规范。

设计原则

• URL即资源，使用名词表示资源
• 接口应直观、简洁、风格命名保持一致
• 必须版本化，具有足够的灵活性来支持上层UI
• 使用HTTP方法进行操作：利用 HTTP 方法对应 CRUD 操作，即 GET 读取、POST 创建、PUT 更新、DELETE 删除
• 无状态通信：服务器端不保存客户端的状态，每个请求都是独立的。
• 使用 HTTP 状态码表示请求结果：服务器使用标准的 HTTP 状态码来通知客户端请求的结果，从而使客户端能清晰地理解操作是否成功

设计规范

1.将版本号放入URL中

应该将API的版本号放入URL。 版本号以字符'v'开头，比如：v1

http://demo.com/cuc/sever/v1

2.使用名词表示资源，使用HTTP Method 描述操作

因为"资源"表示一种实体，所以应该是名词，URL不应该有动词，动词应该放在HTTP协议中，CRUD的操作不要体现在URL中。

查询员工 GET     /v1/employee/1000  新增员工 POST    /v1/employee更新员工 PUT     /v1/employee/1000删除员工 DELETE  /v1/employee/1000

3.资源既可以是单个，也可以是一个集合，比如：user是单个资源，users是集合资源。 由于英文名词的复数规则众多，为了保持接口命名的一致性，我们建议URL里描述集合资源的名词统一使用单数。

查询单个员工 GET     /v1/employee/1000 查询一组员工 GET     /v1/employee

4.使用小写字母，多个单词用"-"分隔，提高URL的可读性

RFC3986 定义了URI是大小写敏感的(除了scheme和host部分)，为了避免歧义，接口路径应尽量使用小写字母。

对于由多个单词构成的路径，推荐使用'-'(hyphen)分隔，避免使用驼峰命名（camelCase）、下划线命名(snake_case)、首字母大写的驼峰命名（PascalCase），以提高可读性。

camelCase  :  /v1/customer/1000/shippingAddress  [Bad]snake_case :  /v1/customer/1000/shipping_address [Bad]PascalCase :  /v1/customer/1000/ShippingAddress  [Bad]hyphen     :  /v1/customer/1000/shipping-address [OK]

5.资源嵌套层次避免过深，尽量不超过2层

定义REST接口时，通常使用资源嵌套（多级路径）来标识资源之间的关系，资源嵌套层次尽量不超过2层，否则很难阅读和使用。

GET  /v1/user/1000/company    查询ID等于1000的用户的公司信息GET  /v1/user/1000/company/10 查询ID等于1000的用户所属公司中ID=10的公司信息，嵌套两层

6.接口URL尽量保持简短，对于集合资源不同纬度的筛选，可通过组合不同的Query Param来实现。

GET /v1/employee?state=internal&title=senior

反面案例

GET /v1/externalEmployeesGET /v1/internalEmployeesGET /v1/internalAndSeniorEmployees

7.排序

单个字段排序

GET /v1/employee?sort=age&order=ascGET /v1/employee?sort=age&order=desc

多个字段排序

字段名前缀,'+'：表示升序，'-'：降序，多个字段名以逗号分隔

GET /v1/employee?sort=+age,-userName

8.分页

对于数据量比较大的集合资源，接口实现一定要支持分页。

常规分页有两个重要的参数：

pageNo 获取那一页的记录，默认第一页。

pageSize 每页返回多少条数据，推荐默认值25，必须限定此参数的最大值。

返回的资源列表为：[(pageNo-1)pageSize, pageNopageSize)

GET /v1/employee?pageNo=8&pageSize=20&sort=age&order=desc

9.字段选择

调用方可能只需要资源的少量属性，接口提供方可支持客户端通过请求参数fields来选择返回的字段，多个字段以逗号分隔，示例如下：

GET /v1/employee?fields=id,name,age&pageNo=1&pageSize=20&sort=age&order=desc

和以前使用接口的区别

参考链接

https://blog.csdn.net/qq_55806761/article/details/135425645​

阅读原文：https://mp.weixin.qq.com/s/kq-lHAeVjy-ShQL5qK7iQg