REST API 设计最佳实践

发布时间:2024年01月03日

我的新书《Android App开发入门与实战》已于2020年8月由人民邮电出版社出版,欢迎购买。点击进入详情

“应用程序编程接口”或 API 是指各种软件服务之间的通信通道。传输请求和响应的应用程序分别称为客户端和服务器。

有不同类型的API 协议:

  • REST?— 依赖于客户端/服务器方法,将 API 的前端和后端分开,并在开发和实现方面提供相当大的灵活性。
  • RPC?— 远程过程调用 (RPC) 协议发送多个参数并接收结果。
  • SOAP?— 支持 Internet 上的各种通信协议,例如 HTTP、SMTP 和 TCP。
  • WebSocket?— 提供了一种通过持久连接在浏览器和服务器之间交换数据的方法。

什么是 API?(来源:RapidAPI)

作为软件工程师,我们的大部分日常工作都会使用或创建 REST API。系统之间通信的标准方法是通过 API。因此,正确构建 REST API 以避免将来出现问题至关重要。定义良好的 API 应该易于使用、简洁且不易误用

以下是一些一般性建议:

1.使用名词代替动词

? 不应在端点路径中使用动词。相反,路径名应包含标识我们正在访问或更改的端点所属对象的名词。

例如,不要使用/getAllClients来获取所有客户端,而是使用/clients.

2.使用复数资源名词

? 对资源名词使用复数形式,因为这适合所有类型的端点。

例如,不要使用/employee/:id/,而是使用/employees/:id/.

3. 保持一致

? 当我们说保持一致时,这意味着是可预测的。当我们定义了一个端点时,其他端点的行为也应? ? ? 该类似。因此,对资源使用相同的情况,对所有端点使用相同的身份验证方法,相同的标头,? ? ? 相同的状态代码等。

4. 保持简单

? 我们应该按原样将所有端点命名为面向资源的。如果我们想为用户定义一个API,我们会将其描? ? 述为:

/users

/users/124

因此,第一个 API 获取所有用户,第二个 API 获取特定用户。

5. 用户正确的状态码

? 这一点超级重要。HTTP 状态码有很多,但我们通常只使用其中的一些。不要使用太多,但对? ? ? API 中的相同结果使用相同的状态代码,例如,

  • 200表示普遍成功。
  • 201创建成功。
  • 202表示请求成功。
  • 204表示没有内容。
  • 307用于重定向内容。
  • 400错误请求。
  • 401表示未经授权的请求。
  • 403缺少权限。
  • 404缺少资源。
  • 5xx表示内部错误。

HTTP 状态代码

6. 不要返回纯文本

? REST API 应接受 JSON 作为请求负载并使用JSON进行响应,因为它是传输数据的标准。然? ? ? 而,仅仅返回一个 JSON 格式的字符串是不够的;我们需要将 Content-Type 标头指定为? ? ? ? ? ? ? application/JSON。唯一的例外是我们尝试在客户端和服务器之间发送和接收文件。

7. 进行适当的错误处理

? 在这里,我们希望消除发生错误时的任何混乱。我们必须正确处理错误并返回指示发生了什么? ? ? 的响应代码(从400 到 5xx 错误)。我们需要在响应正文中返回一些详细信息以及状态代码。

8. 有良好的安全实践

? 我们希望客户端和服务器之间的所有通信都受到保护,这意味着我们需要始终使用 SSL/TLS,? ? 无一例外。此外,允许通过 API 密钥进行身份验证,该密钥应使用带有到期日期的自定义? ? ? ? ? ? HTTP标头进行传递。

9.使用分页

? 如果我们的 API 需要返回大量数据,请使用分页,因为这将使我们的 API 面向未来。此处推荐? ? 使用pagepage_size

例如,/products?page=10&page_size=20

10. 版本控制

? 从第一个版本开始对 API 进行版本控制至关重要,因为我们的 API 可能有不同的用户。这将使? ? 我们的用户避免受到我们将来可能做出的更改的影响。API 版本可以通过 HTTP 标头或查询/路? ? 径参数传递。

例如,/products/v1/4

另外,不要忘记记录您的 API,因为 API 的好坏取决于其文档。文档应显示完整请求/响应周期的示例。在这里,我们可以使用OpenAPI定义作为事实来源。

要开发 API,请检查SwaggerOpenAPI规范、PostmanStoplight

文章来源:https://blog.csdn.net/ddnosh/article/details/135356209
本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。