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

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

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

什么是 Web API？

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

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资源之间维护清晰的层次结构。

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

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

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

使用合适的 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 时要考虑的另一个重要方面是安全性。以下是需要记住的一些要点：

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