REST API 设计最佳实践

我的新书《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 面向未来。此处推荐    使用page和page_size

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

10. 版本控制

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

例如，/products/v1/4

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

要开发 API，请检查Swagger和OpenAPI规范、Postman或Stoplight。