如何设计和开发Web API：开发人员的基本指南

软件应用程序在很多方面使我们的生活更加轻松和美好。我们几乎每天都在使用它们，有些人发现自己使用应用程序的频率比与他人互动的频率还要高。

但是应用程序如何相互交互呢？它们通过 API（应用程序编程接口）来实现。在本文中，您将了解什么是 API。我们将特别关注 Web API 及其设计和开发。

什么是 Web API？

Web API 是一种旨在通过 Web 使用的 API。换句话说，基于 Web 的软件应用程序、系统和服务使用 Web API 通过互联网交换信息。它们发送请求并接收响应，通常采用 JSON 或 XML 等格式。

Web API 在现代软件开发中发挥着至关重要的作用，原因如下：

1. 互操作性：API 与技术无关，这意味着它们允许不同的软件系统相互通信，而不受技术堆栈的限制。这使开发人员能够无缝集成各种应用程序。
2. 可扩展性：Web API 支持模块化开发，使得应用程序的各个组件可以独立构建、调试和扩展，大大提高了系统的可扩展性。
3. 灵活性和可扩展性：通过遵循标准实践和明确定义的规则，Web API 可帮助应用程序扩展其功能。它们还具有足够的灵活性，可让开发人员创建动态应用程序。

开发 Web API 的方法

可以根据需求使用各种方法来开发 Web API。以下是一些常用的方法：

• REST – 表述性状态转移 (REST) API 使用 HTTP 协议执行操作。它们以无状态的方式运行，这意味着每个请求都必须包含接收方处理和响应所需的所有信息。
• SOAP——简单对象访问协议使用 XML 以结构化的方式交换信息。
• GraphQL – 用于查询和操作 API。
• gRPC——一种使用 HTTP/2 传输信息的远程过程调用框架。

关于GraphQL API和gRPC API的比较可以查看相关博客文章

在接下来的部分中，我们将探讨 API 的设计和开发，重点关注 REST API 作为我们讨论的核心协议。

了解要求和目标

在任何软件开发过程中，在开始之前了解需求和预期用例至关重要。这有助于您规划和估算项目所需的成本、时间和其他资源。

构建 RESTful API 时也是如此。您需要确定应用程序是否以无状态方式交换信息，所涉及的实体是否可以表示为资源，以及服务是否足够灵活以处理不同的数据格式。

定义资源和端点

REST API 以资源为中心，资源是代表系统中数据或对象的实体。每个资源都由一个称为资源标识符的唯一 URI 标识。这些资源可以通过端点访问和操作，端点是接收和处理来自客户端的请求的特定 URL。

最佳实践建议在端点中使用名词来表示资源，而不是使用可能表示对资源进行操作的动词。

请考虑以下示例：https://api.example.com/products

端点遵循使用名词表示资源的最佳实践（在本例中为products）。注意我如何使用复数形式 – 产品？如果您正在处理对象集合，也建议使用复数。

但是，不建议使用以下端点，https://api.example.com/add-product因为它使用动词并尝试描述对资源的操作。对于更复杂的操作，这种方法可能会变得复杂。

标准端点命名约定的另一个重要方面是使用层次结构。这有助于清楚地表示资源之间的关系。

例如：https://api.example.com/categories/{categoryId}/products/{productId}。
在这里，我们定义一个端点，在category和product资源之间维护清晰的层次结构。

使用 HTTP 方法和状态代码

在 REST API 中，HTTP用于客户端和服务器之间的通信。HTTP 具有主要用于对资源执行操作的标准方法。以下是这些方法及其用途的列表：

• GET – 获取资源的详细信息。这些详细信息由服务器在响应消息正文中返回。
• POST – 创建新资源。要创建的资源的详细信息在请求消息正文中发送。
• PUT – 根据资源的可用性创建或更新资源。要创建或更新的资源的详细信息在请求消息正文中发送。
• DELETE – 删除资源。
• PATCH – 部分更新资源。对资源所做的更改在请求消息正文中发送。

开发定义良好的 REST API 的推荐方法是正确使用这些 HTTP 方法对资源执行相应的 CRUD（创建、读取、更新、删除）操作。此外，您还应确保 API 在响应消息正文中使用适当的 HTTP 状态代码响应客户端。

状态代码反映请求的最终结果。以下是一些您可以使用的常见 HTTP 状态代码：

• 200 正常
• 201 已创建
• 204 无内容
• 400 错误请求
• 401 未授权
• 403 禁止
• 404 未找到
• 500 内部服务器错误
• 503 服务不可用
• 504 网关超时

使用合适的 HTTP 状态代码来准确表示 API 端点正在处理的请求的结果。您还可以实现自定义 HTTP 状态代码来描述特定于应用程序的行为。

版本控制策略

随着时间的推移，您开发的 API 会不断发展，您会对其进行更改。此时版本控制策略就变得非常重要。您必须确保已经使用您的 API 的客户端不会受到您所做的更改的影响。

维护不同的版本将使您的 API 向后兼容，并允许客户端根据自己的需求使用首选版本的 API。Postman网站上这篇信息丰富的博客的摘录解释了何时对 API 进行版本控制是理想的：

“每当您做出需要用户修改代码库才能继续使用 API 的更改时，您都应该对 API 进行版本控制。这种更改称为“重大更改”，可以对 API 的输入和输出数据结构、成功和错误反馈以及安全机制进行更改。”

API 版本控制可以通过多种方式进行。以下是一些方法：

• URI 版本控制：在 URL 路径中包含版本号。例如，https://api.example.com/v1/products。
• 查询参数版本控制：在 URL 中指定版本号作为查询参数。例如，https://api.example.com/products?version=1。
• 标头版本控制：在请求的 HTTP 标头中包含版本号。例如，使用自定义标头，如X-API-Version: 1。
• 内容协商：在请求的标头中指定版本Accept，通常使用媒体类型。例如Accept: application/vnd.example.v1+json。
• 嵌入版本控制：将版本号嵌入响应的媒体类型中。例如，application/vnd.example.product-v1+json。

安全注意事项

开发 API 时要考虑的另一个重要方面是安全性。以下是需要记住的一些要点：

1. 实施 HTTPS 来加密客户端和服务器之间交换的信息。
2. 实施身份验证和授权，确保只有拥有正确权限的用户才能对资源执行操作。常用方法包括基本身份验证、Bearer 或 Token 身份验证、JWT 和 OAuth 2.0。此外，实施基于角色的访问控制来管理资源访问。
3. 实施输入验证和清理以防止 SQL 注入和跨站点脚本 (XSS) 等漏洞攻击。
4. 实施速率限制和节流，以控制客户端在特定时间范围内向服务器发出的请求数量。这有助于防止服务器负载过大。

文档

API 开发中一个关键但经常被忽视的方面是文档。记录 API 至关重要，这样用户才能了解其特性和功能。

文档必须全面、易懂且遵循标准做法。包括请求和响应主体的示例、使用的 HTTP 状态代码等。您可以遵循Open API 规范来描述您的 RESTful API。

排序、过滤和分页策略

如果您开发的 API 返回的记录过多，则可能会导致性能问题。检索大量数据然后对其进行排序或过滤效率很低。

为了解决这个问题，您应该启用记录排序和过滤功能。您还应该实现分页功能，以细分要获取的记录数量，并设置限制，以便于导航和处理。

监控使用情况、日志记录和运行状况

记录 API 请求和响应以帮助调试是一个好主意。监控 API 使用情况将帮助您了解应用程序的整体性能和行为。定期进行健康检查可以帮助您在出现任何问题时采取必要的措施。所有这些步骤都将使 API 更加强大和可靠。

结论

API，特别是 Web API，对于软件应用程序通过互联网进行通信至关重要。

本文介绍了什么是 Web API、它们为何重要以及开发它们的不同方法，重点介绍了 REST API。您还了解了关键主题，例如定义资源和端点、使用标准 HTTP 方法和状态代码、版本控制策略、安全注意事项、文档等。