RESTful API 是应用程序接口 (API) 的一种架构风格,它使用 HTTP 请求来访问和使用数据。该数据可用于 GET、PUT、POST 和 DELETE 数据类型,这些数据类型是指有关资源的操作的读取、更新、创建和删除。
注意:RESTful是一种风格而不是标准。
使用RESTful风格的接口,从接口上可能只能定位其资源,但是无法知晓它具体进行了什么操作,需要具体了解其发生了什么操作动作要从其HTTP请求方法类型上进行判断。具体的HTTP方法和方法含义如下:
当然也有很多在具体使用的时候使用PUT表示更新。从请求的流程来看,RESTful API和传统API大致架构如下:
在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请求方法的安全性和幂等性如下:
HTTP Method | 资源操作 | CRUD操作 | 安全性 | 幂等性 | 解释 |
---|---|---|---|---|---|
GET | SELECT | SELECT | 安全 | 幂等 | 读操作安全,查询一次多次结果一致 |
POST | INSERT | CREATE | 非安全 | 非幂等 | 写操作非安全,每多插入一次都会出现新结果 |
PUT | UPDATE | UPDATE | 非安全 | 幂等 | 写操作非安全,一次和多次更新结果一致 |
DELETE | DELETE | DELETE | 非安全 | 幂等 | 写操作非安全,一次和多次删除结果一致 |
幂等性: 对同一REST接口的多次访问,得到的资源状态是相同的。
安全性: 对该REST接口访问,不会使服务器端资源的状态发生改变。
既然了解了RESTful的一些规则和特性,那么具体该怎么去设计一个RESTful API呢?
操作应该使用 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
在URI中使用名词来表示资源,而不是动词,以避免歧义和混淆。对于表示资源集合的URI,通常使用复数形式,以便明确表示这是一个集合而不是单个资源。例如:
# 推荐
/users # 用户资源
/orders # 订单资源
# 避免
/user
/order
RESTful API 应该使用 URI 来定位资源,以确保每个资源都有一个唯一的标识符。URI 应该具有层级结构,以便表示资源之间的关系。例如:
GET /users/1/orders/1
使用查询参数来过滤和分页资源,例如:“?page=1 & limit=10”
获取前10个用户: GET /users?limit=10
获取第二页的用户: GET /users?page=2&limit=10
使用 合适的HTTP 状态码来表示请求结果,以便客户端能够根据状态码进行处理。例如:。状态码主要分为五大类:
1xx:相关信息
2xx:操作成功
3xx:重定向
4xx:客户端错误
5xx:服务器错误
例如:
使用 JSON 或 XML 来表示数据,以便不同的客户端能够方便地进行数据解析和处理。例如:
GET /users/1
{
"id": 1,
"name": "Tom",
"age": 25
}
RESTful API 应该使用版本号来管理 API 的不同版本,以便支持旧版 API 的兼容性和平稳升级。应该将API的版本号放入URL。 版本号以字符'v'开头,比如:v1、v2
/v1/users
/v2/users
在响应中包含清晰、详细的错误信息,帮助客户端理解问题的原因和解决方案。
{
"error": {
"code": 404,
"message": "User not found"
}
}
使用HTTP头部中的Accept和Content-Type字段进行内容协商,以确定客户端期望的表示形式和服务器返回的表示形式。
接受JSON格式的响应:Accept: application/json
发送JSON格式的请求体:Content-Type: application/json
在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 固然很好很规范,但大多数互联网公司并没有按照或者完全按照其规则来设计,因为REST是一种风格,而不是一种约束或规则,过于理想的RESTful API 会付出太多的成本。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。