余晖落尽暮晚霞,黄昏迟暮远山寻
本站
当前位置:网站首页 > 编程知识 > 正文

每个开发人员都应该了解的 REST 端点最佳实践

xiyangw 2023-10-03 16:24 21 浏览 0 评论


作为软件开发人员,您可能会经常遇到 RESTful API。

REST(表述性状态传输)是一种用于设计网络应用程序的架构风格,遵守其原则对于创建可扩展、可维护和高效的 Web 服务至关重要。 在这篇博文中,我们将深入研究设计 REST 端点的最佳实践,并提供示例,以帮助您构建强大且用户友好的 API。

REST 服务没有严格的命名规则,我们可以自由地按照我们想要的方式实现它们,但是,有一定的指导原则可以确保我们的 REST API 易于阅读、一致和直观。

把事情简单化

这并非特定于资源命名指南,而是设计 API 时的一个重要概念。 我们的 REST API 命名应该是自描述的并且尽可能简单。 命名我们的 API 时的重要原则之一是允许开发人员在不参考文档的情况下进行工作。

/api/users/12345 ?
/api?type=user&id=12345 ?

看第二个例子,在我们一起查看 type 和 id 字段之前,不清楚我们要做什么。

使用复数名词为 RESTful URI 命名

设计 RESTful 端点的一个关键原则是使用名词来表示资源并使用复数名称以保持一致性。 这使您的 API 更加直观且易于理解。 请记住避免在端点名称中使用动词或操作,因为 HTTP 方法已经传达了该操作。

由于 REST API 执行的最常见操作之一是获取数据,因此使用复数更加直观和简单。

GET Users -> /api/users ?
GET User account -> /api/users/{userId} ?
GET User's rights -> /api/users/{userId}/rights ?
GET Users -> /api/getAllUsers ?

请记住以下几点:

命名资源时不要混合单数和复数约定。 为了可读性,它应该在整个 API 中保持一致。

URL 表示资源,可以是单例,也可以是集合。 复数表示给定 URI 下的所有资源。

/api/customers -> represent all customers.
/api/customers/{id} -> represents specific customer under this resource
  • 给定资源还可以包含子集合。
/api/customers/{id}/orders
/api/customers/{id}/orders/{order-id}

坚持标准 HTTP 方法

对于 CRUD 操作(创建、读取、更新和删除),请始终使用标准 HTTP 方法。 这可确保 API 的一致性,并帮助开发人员更快地了解您的端点。

POST(创建):创建新资源

GET(读取):检索资源或资源集合

PUT(更新):更新资源

DELETE(删除):删除资源

POST /users         // Create a new user
GET /users          // Get all users
GET /users/{id}     // Get a specific user
PUT /users/{id}     // Update a specific user
DELETE /users/{id}  // Delete a specific user

切勿在 URI 中使用 CRUD 函数名称

我们不应该使用 URI 来指示 CRUD 功能。 URI 只能用于唯一标识资源,而不应用于对资源执行任何操作。

/api/getUsers ?
/api/getUserRights ?
GET /api/users ?
GET /api/users/12345/rights ?

我们应该使用 HTTP 请求方法来指示执行哪个 CRUD 功能。

使用正斜杠 (/) 表示层次关系

正斜杠 (/) 字符用在 URI 的路径部分中以指示资源之间的层次关系。

/api/users/{userId}/rights
/api/customers/{id}/orders

使用连字符 (-)

为了使您的 URI 易于人们扫描和解释,请使用连字符 (-) 来提高长路径段中名称的可读性。

/api/customers/{id}/addresses/{address-id}
/api/customers/{id}/shipping-addresses/{address-id}

避免使用下划线 (_)

建议在命名 URI 时避免使用下划线。 根据应用程序的字体,下划线 (_) 字符可能会在某些浏览器或屏幕中部分被遮挡或完全隐藏。

为了避免这种混淆,请使用连字符 (-) 而不是下划线 (_)。

采用查询参数以获得灵活性

在构建 RESTful API 时,我们会遇到多种需求,需要通过以下方式收集资源:

排序

从集合中过滤我们的某些结果

基于某些条件的有限结果

不要为这些需求创建新的 API,而是在资源收集 API 中启用排序、过滤和分页功能,并将输入参数作为查询参数传递。 这可以让您的 API 保持干净,并为开发人员提供更大的灵活性。

GET /users?gender=male&age=25-35&sort=age,desc&page=1&size=10

版本控制很重要:保持一致

API 版本控制对于保持向后兼容性以及在更改 API 时实现平稳过渡至关重要。 将版本号包含在 URL 中或作为请求标头以保持一致性。

// URL versioning
GET /api/v1/users
// Header versioning
GET /api/users
Accept: application/vnd.example.v1+json

使用正确的状态代码进行通信

使用正确的 HTTP 状态代码通知客户端其请求的结果。 这有助于开发人员更有效地处理错误并了解 API 调用的结果。

常见状态码:

200 OK:成功的 GET 或 PUT 请求

201 已创建:POST 请求成功

204 无内容:成功的 DELETE 请求

400 Bad Request:无效的客户端请求

401 Unauthorized:请求需要身份验证

403 Forbidden:客户端缺少权限

404 Not Found:未找到请求的资源

500 Internal Server Error:服务器端错误

通过 HATEOAS 提高可发现性

超媒体作为应用程序状态引擎 (HATEOAS) 是一种 RESTful 设计原则,鼓励在 API 响应中提供指向相关资源的链接。 这提高了可发现性,并使开发人员能够轻松导航您的 API。

GET /users/123
{
  "id": 123,
  "name": "John Doe",
  "links": [
    {
      "rel": "self",
      "href": "/users/123"
    },
    {
      "rel": "edit",
      "href": "/users/123/edit"
    },
    {
      "rel": "delete",
      "href": "/users/123"
    }
  ]
}

全面的文档:必备

API 的好坏取决于其文档。 清晰、一致和交互式的文档对于开发人员有效理解和使用您的 API 至关重要。 利用 Swagger 或 API Blueprint 等工具为您的端点生成全面的文档。

结论

设计 RESTful API 是现代软件开发的一个组成部分。 通过遵循这些最佳实践,您将创建强大、可维护且用户友好的 API,使开发人员能够更轻松地与您的 Web 服务交互。

请记住关注资源名称、使用标准 HTTP 方法、包含查询参数、保持一致的版本控制、使用正确的状态代码、实施 HATEOAS 并提供全面的文档。

这些实践将使您走上设计开发人员喜欢使用的一流 REST 端点的道路。

相关推荐

华为交换机配置命令总结

1、配置文件相关命令[Quidway]displaycurrent-configuration显示当前生效的配置[Quidway]displaysaved-configuration显示fla...

解决账户无法登录的故障
解决账户无法登录的故障

在优化系统时错误地根据网上的提示,将唯一的Administrator账户设置为禁用,导致重启后无法进入系统。类似的故障还有使用组策略限制本地账户登录,导致重启后...

2023-10-11 17:16 xiyangw

S5720交换机登录提示初始密码存在安全风险
S5720交换机登录提示初始密码存在安全风险

问题描述客户每次登录输密码时,提示初始密码不安全,现在客户嫌麻烦想要去掉:Username:huaweiPassword:Warning:Theinitia...

2023-10-11 17:15 xiyangw

Springboot,Mybatis修改登录用户的密码
Springboot,Mybatis修改登录用户的密码

一、Mybatis.xml<updateid="changePassword"parameterType="string...

2023-10-11 17:15 xiyangw

PHP理论知识之沐浴更衣重看PHP基础(二)
PHP理论知识之沐浴更衣重看PHP基础(二)

接上篇,咱们继续讲解PHP基础八、标准PHP组件和框架的数量很多,随之产生的问题就是:单独开发的框架没有考虑到与其他框架的通信。这样对开发者和框架本身都是不利的...

2023-10-11 17:15 xiyangw

新鲜出炉UCloud云主机“数据方舟”评测报告(5)— — 关其城
新鲜出炉UCloud云主机“数据方舟”评测报告(5)— — 关其城

2015年10月29日,UCloud云主机黑科技——“数据方舟”功能正式上线,首轮内测随即开放。截止至2015年12月6日,我们共收到了534位用户的评测申...

2023-10-11 17:14 xiyangw

业余无线电Q简语及英文缩语
业余无线电Q简语及英文缩语

Q简语:语音通信及CW通信通用(加粗为常用)QRA电台何台QRB电台间之距离QRG告之正确频率QRH频率是否变动QRI发送音调QRJ能否收到QRK信号之可...

2023-10-11 17:14 xiyangw

非常详细!如何理解表格存储的多版本、生命周期和有效版本偏差
非常详细!如何理解表格存储的多版本、生命周期和有效版本偏差

表格存储在8月份推出了容量型实例,直接支持了表级别最大版本号和生命周期,高性能实例也将会在9月中旬支持这两个特性。那么,最大版本号和生命周期以及特有的...

2023-10-11 17:14 xiyangw

H3C交换机恢复出厂和各种基本配置,这20个要点你知道吗?
H3C交换机恢复出厂和各种基本配置,这20个要点你知道吗?

私信“干货”二字,即可领取138G伺服与机器人专属及电控资料!H3C交换机不知道密码如何恢复出厂设置1、开机启动,Ctrl+B进入bootrom菜单,选择恢复出...

2023-10-11 17:13 xiyangw

在使用移动支付系统的时候如何保护信息安全?

移动支付的方式近年来不断被更新,使得Venmo(据嘉丰瑞德理财师了解,此为美国的“支付宝”)之类的支付方式已经可以某种意义上代替随身携带现金了。但是你必须防范那些第三方应用程序轻松地获取你的银行卡以及...

界面控件DevExpress WinForms MVVM入门指南——登录表单(下)

从本文档中,您将了解如何向应用程序添加登录表单。在本节教程中着重讨论了如何实现此任务,这基本上是附加应用程序功能的一部分。DevExpressUniversalSubscription官方最新版免...

linux基础命令(一)
linux基础命令(一)

为啥要学linux?您可能熟悉WindowsXP、Windows7、Windows10和MacOSX等操作系统。Linux就是这样一种强大的操...

2023-10-11 17:13 xiyangw

MySQL数据库密码忘记了,怎么办?

#头条创作挑战赛#MySQL数据库密码忘记了且没有其他可以修改账号密码的账户时怎么办呢?登录MySQL,密码输入错误/*密码错误,报如下错误*/[root@TESTDB~]#mysql-u...

MobaXterm忘记Session密码,如何查看已保存的密码
MobaXterm忘记Session密码,如何查看已保存的密码

MobaXterm工具登录过SSH终端后,如果存储了Session(存储后再连接ssh的时候只需要输入账号不需要输入密码就可以直接连接上ssh),则可以...

2023-10-11 17:12 xiyangw

华为交换机密码丢失修改方法
华为交换机密码丢失修改方法

华为S2300交换机找回密码设置一、目的交换机的console和telnet密码丢失,无法登录设备。交换机已进行过数据配置,要把密码恢复而数据配置不能丢失。二、...

2023-10-11 17:12 xiyangw

取消回复欢迎 发表评论: