Restful API 接口规范详解

什么是RESTful API ?

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

注意：RESTful是一种风格而不是标准。

HTTP方法

使用RESTful风格的接口，从接口上可能只能定位其资源，但是无法知晓它具体进行了什么操作，需要具体了解其发生了什么操作动作要从其HTTP请求方法类型上进行判断。具体的HTTP方法和方法含义如下：

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

当然也有很多在具体使用的时候使用PUT表示更新。从请求的流程来看，RESTful API和传统API大致架构如下：

传统url接口与RESTful风格接口的区别

在restful风格中，将互联网的资源抽象成资源，将获取资源的方式定义为方法，从此请求再也不止get和post了：

客户端请求					传统url接口							REST ful风格接口
查询所有用户				    /user/findAll						GET /users
查询编号为1的用户		        /user/findById?id=1			GET /user/1         
新增一个用户				    /user/save							POST /user
修改编号为1的用户		        /user/update						PUT /user/1
删除编号为1的用户		        /user/delete?id=1				DELETE /user/1

安全性和幂等性

在谈及GET、POST、PUT、DELETE的时候，就必须提一下接口的安全性和幂等性。上述四个HTTP请求方法的安全性和幂等性如下：

幂等性： 对同一REST接口的多次访问，得到的资源状态是相同的。

安全性： 对该REST接口访问，不会使服务器端资源的状态发生改变。

RESTful API设计规范

既然了解了RESTful的一些规则和特性，那么具体该怎么去设计一个RESTful API呢？

1、使用 HTTP Method 动词来表达操作

操作应该使用 HTTP 动词来表达，例如 GET（获取资源）、POST（创建资源）、PUT（更新资源）、DELETE（删除资源） 等，以确保对资源的操作被明确表示和限制。如下所示：

GET /users           # 获取用户列表
GET /users/{id}      # 获取单个用户
POST /users          # 创建新用户
PUT /users/{id}      # 更新用户信息
DELETE /users/{id}   # 删除用户

CRUD的操作不要体现在URL中。避免getUsers、createUser、findUsers、addUsers、updateUsers、deleteUsers等。

查询用户 GET     /findUsers?id=1000  
新增用户 POST    /addUsers
更新用户 POST    /updateUsers?id=1000
删除用户 POST    /deleteUsers?id=1000

2、使用名词来表示资源

在URI中使用名词来表示资源，而不是动词，以避免歧义和混淆。对于表示资源集合的URI，通常使用复数形式，以便明确表示这是一个集合而不是单个资源。例如：

# 推荐
/users						# 用户资源
/orders						# 订单资源

# 避免
/user
/order

3、使用 URI 来定位资源

RESTful API 应该使用 URI 来定位资源，以确保每个资源都有一个唯一的标识符。URI 应该具有层级结构，以便表示资源之间的关系。例如：

GET /users/1/orders/1

4、使用查询参数来过滤和分页

使用查询参数来过滤和分页资源，例如：“?page=1 & limit=10”

获取前10个用户：		GET /users?limit=10
获取第二页的用户：		GET /users?page=2&limit=10

5、使用 HTTP 状态码来表示请求结果

使用 合适的HTTP 状态码来表示请求结果，以便客户端能够根据状态码进行处理。例如：。状态码主要分为五大类：

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

例如：

• 200：请求成功
• 201：资源创建成功
• 400：请求参数错误
• 401：未授权访问
• 403：表示禁止访问资源。
• 404：表示未找到资源。
• 500：表示服务器内部错误。

6、使用 JSON 或 XML 来表示数据

使用 JSON 或 XML 来表示数据，以便不同的客户端能够方便地进行数据解析和处理。例如：

GET /users/1
{
  "id": 1,
  "name": "Tom",
  "age": 25
}

7、使用版本号来管理 API

RESTful API 应该使用版本号来管理 API 的不同版本，以便支持旧版 API 的兼容性和平稳升级。应该将API的版本号放入URL。 版本号以字符'v'开头，比如：v1、v2

/v1/users
/v2/users

8、提供清晰的错误信息：

在响应中包含清晰、详细的错误信息，帮助客户端理解问题的原因和解决方案。

{
  "error": {
    "code": 404,
    "message": "User not found"
  }
}

9、使用标准的HTTP头部：

使用HTTP头部中的Accept和Content-Type字段进行内容协商，以确定客户端期望的表示形式和服务器返回的表示形式。

接受JSON格式的响应：Accept: application/json
发送JSON格式的请求体：Content-Type: application/json

URI书写规范

在RESTful API设计中，URI（Uniform Resource Identifier）的书写通常遵循一些规范和最佳实践，以提高可读性、一致性和可维护性。以下是一些关于URI书写的常见规范：

使用小写字母：

建议使用小写字母，因为URI是区分大小写的。。

# 推荐
/users
/articles

# 避免
/Users
/Articles

使用短划线或下划线分隔单词：

使用短划线（-）或下划线（_）来分隔单词，而不是使用空格或驼峰命名法。这有助于确保URI的可读性。

# 推荐
/user-profiles
/article-comments

# 避免
/userProfiles
/articleComments

避免使用空格和特殊字符：

URI中不应包含空格和特殊字符，可以使用短划线或下划线来替代。

# 推荐
/user-profiles
/article-comments

# 避免
/user profiles
/article@comments

避免深层嵌套：

尽量避免过深的嵌套结构，以保持URI的简洁性和易读性。

# 推荐
/users/{userId}/orders
/articles/{articleId}/comments

# 避免
/users/{userId}/orders/{orderId}/items
/articles/{articleId}/comments/{commentId}/replies

RESTful API案例

详情请见：https://restfulapi.cn/

总结

RESTful风格的API 固然很好很规范，但大多数互联网公司并没有按照或者完全按照其规则来设计，因为REST是一种风格，而不是一种约束或规则，过于理想的RESTful API 会付出太多的成本。

我正在参与2023腾讯技术创作特训营第三期有奖征文，组队打卡瓜分大奖！