在这篇深入探讨中，我们将从基础开始，逐步介绍 API 设计，并探讨定义卓越 API 的最佳实践。

作为一名开发者，你可能已经熟悉了许多这些概念，但我将提供详细解释，以加深你的理解。

API 设计：电子商务示例

让我们考虑一个像 Shopify 这样的电子商务平台的 API，如果你不熟悉， Shopify 是一个知名的电子商务平台，允许企业建立在线商店。

在 API 设计中，我们关注的是定义 API 的 输入（比如新产品的产品详情）和 输出（比如查询产品时返回的信息）。

这意味着我们关注的是接口，而非底层实现。

API 设计与 CRUD：

因此，重点主要在于定义如何向用户或与您的电子商务 API 交互的系统公开 CRUD 操作。

CRUD 代表创建 (Create)，读取 (Read)，更新 (Update)，删除 (Delete)。这些是任何数据驱动应用程序的基本操作。

例如，要添加新产品（创建），您需要向/api/products发送 POST 请求，其中产品详情包含在请求体中。

要检索产品（读取），您需要通过 GET 请求从/products获取数据。

对于更新产品信息（更新），我们使用 PUT 或 PATCH 请求到/products/:id，其中 id 是我们需要更新的产品的 id。

删除与更新类似；我们向/products/:id发送 DELETE 请求，其中 id 是我们需要删除的产品（删除）。

通讯协议和数据传输机制

另一部分是决定将使用的通讯协议，如 HTTP、WebSockets 等，以及数据传输机制：JSON、XML 或 Protocol Buffers。

这适用于 RESTful APIs，但我们也有 GraphQL 或 gRPC 范式。

API 范式

API 有不同的范式，每种范式都有自己的协议和标准。都可使用 Apifox 来调试。

REST（表现层状态转换）

优点： 无状态：客户端对服务器的每个请求都必须包含理解和完成请求所需的所有信息。使用标准 HTTP 方法（GET、POST、PUT、DELETE）。易于被不同客户端（浏览器、移动应用）使用。

缺点： 这可能导致数据的过度获取或获取不足——因为可能需要更多的终端来访问特定数据。

特点： 支持分页、过滤（limit、offset）和排序。使用 JSON 进行数据交换。

GraphQL

优点： 允许客户端请求他们确切需要的内容，避免过度和不足地获取数据。强类型、基于模式的查询。

缺点： 复杂查询可能会影响服务器性能。所有请求都作为 POST 请求发送。

特点： 通常即使在出错的情况下也响应 HTTP 200 状态码，错误详情在响应体中。

gRPC（谷歌远程过程调用）

优点： 基于 HTTP/2，提供了如多路复用和服务器推送等高级功能。使用 Protocol Buffers，这是一种语言中立、平台中立、可扩展的结构化数据序列化方式。在带宽和资源方面效率高，特别适合微服务。

缺点： 与 JSON 相比可读性较差。需要 HTTP/2 支持。

特点： 支持数据流和双向通信。适用于服务器到服务器的通信。

API 设计中的关系

在电子商务设置中，你可能会有像用户到订单、订单到产品等关系。

设计端点以反昘这些关系是重要的。例如，在此场景中，GET /users/{userId}/orders应该获取特定用户的订单。

查询、限制以及 GET 请求的幂等性

常见的查询还包括用于分页的limit和offset，或用于过滤特定日期范围内产品的startDate和endDate。这允许用户检索特定的数据集，而不会一次向系统或用户提供过多信息。

设计良好的 GET 请求是幂等的，意味着多次调用不会改变结果。

GET 请求绝不应更改数据。它们仅用于检索。

向后兼容性和版本控制：

修改端点时，保持向后兼容性很重要。这意味着确保变更不会破坏现有客户。

版本控制：引入版本（如/v2/products）是处理重大更改的常见做法。

在 GraphQL 的情冀下，添加新字段（v2 字段）而不删除旧字段有助于在不破坏现有客户的情况下使 API 演进。

速率限制和 CORS

设置速率限制是另一个最佳实践。这用于控制用户在一定时间内可以进行的请求数量。这对于保持 API 的可靠性和可用性至关重要。它还可以防止 API 遭受 DDoS 击。

通常的做法还包担设置 CORS 设置。跨源资源共享（CORS）设置对于网络安全很重要。它们控制哪些域可以访问您的 API，防止不必要的跨站点互动。

• 源于：https://levelup.gitconnected.com/api-design-101-from-basics-to-best-practices-a0261cdf8886