Restful API 接口规范详解

2023-11-19 23:41:31 浏览数 (1)

什么是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了：

代码语言：txt复制
客户端请求					传统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请求方法的安全性和幂等性如下：

HTTP Method

资源操作

CRUD操作

安全性

幂等性

解释

GET

SELECT

SELECT

安全

幂等

读操作安全，查询一次多次结果一致

POST

INSERT

CREATE

非安全

非幂等

写操作非安全，每多插入一次都会出现新结果

PUT

UPDATE

UPDATE

非安全

幂等

写操作非安全，一次和多次更新结果一致

DELETE

DELETE

DELETE

非安全

幂等

写操作非安全，一次和多次删除结果一致

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

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

RESTful API设计规范

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

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

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

代码语言：shell复制
GET /users           # 获取用户列表
GET /users/{id}      # 获取单个用户
POST /users          # 创建新用户
PUT /users/{id}      # 更新用户信息
DELETE /users/{id}   # 删除用户

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

代码语言：shell复制
查询用户 GET     /findUsers?id=1000  
新增用户 POST    /addUsers
更新用户 POST    /updateUsers?id=1000
删除用户 POST    /deleteUsers?id=1000
2、使用名词来表示资源

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

代码语言：shell复制
# 推荐
/users						# 用户资源
/orders						# 订单资源

# 避免
/user
/order
3、使用 URI 来定位资源

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

代码语言：shell复制
GET /users/1/orders/1
4、使用查询参数来过滤和分页

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

代码语言：txt复制
获取前10个用户：		GET /users?limit=10
获取第二页的用户：		GET /users?page=2&limit=10
5、使用 HTTP 状态码来表示请求结果

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

代码语言：txt复制
1xx：相关信息
2xx：操作成功
3xx：重定向
4xx：客户端错误
5xx：服务器错误

例如：

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

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

代码语言：shell复制
GET /users/1
{
  "id": 1,
  "name": "Tom",
  "age": 25
}
7、使用版本号来管理 API

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

代码语言：shell复制
/v1/users
/v2/users
8、提供清晰的错误信息：

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

代码语言：json复制
{
  "error": {
    "code": 404,
    "message": "User not found"
  }
}
9、使用标准的HTTP头部：

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

代码语言：text复制
接受JSON格式的响应：Accept: application/json
发送JSON格式的请求体：Content-Type: application/json

URI书写规范

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

使用小写字母：

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

代码语言：txt复制
# 推荐
/users
/articles

# 避免
/Users
/Articles
使用短划线或下划线分隔单词：

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

代码语言：txt复制
# 推荐
/user-profiles
/article-comments

# 避免
/userProfiles
/articleComments
避免使用空格和特殊字符：

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

代码语言：txt复制
# 推荐
/user-profiles
/article-comments

# 避免
/user profiles
/article@comments
避免深层嵌套：

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

代码语言：txt复制
# 推荐
/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腾讯技术创作特训营第三期有奖征文，组队打卡瓜分大奖！

RESTfulAPI 2023腾讯·技术创作特训营第三期

0 人点赞