API 设计：从基础到最佳实践

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

在本次深入研究中，我们将从基础开始，逐步了解 API 设计，并逐步实现定义卓越 API 的最佳实践。

作为开发人员，您可能熟悉其中的许多概念，但我将提供详细的解释以加深您的理解。

API 设计：电子商务示例

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

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

这意味着我们专注于接口而不是底层实现

API 设计和 CRUD：

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

CRUD代表创建、读取、更新、删除。这些是任何数据驱动应用程序的基本操作。

例如，要添加新产品（创建），您需要发出 POST 请求，并/api/products在请求正文中发送产品详细信息。

要检索产品（读取），您需要使用 GET 请求来获取数据/products。

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

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

通信协议和数据传输机制

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

RESTful API 就是这种情况，但我们也有 GraphQL 或 gRPC 范例

API 范例

API 有不同的范例，每个范例都有自己的一套协议和标准。

REST（表述性状态转移）

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

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

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

GraphQL

优点： 允许客户端准确请求他们需要的内容，避免过度获取和获取不足。强类型基于架构的查询。

缺点：复杂查询会影响服务器性能。所有请求都以 POST 请求的形式发送。

功能：通常以 HTTP 200 状态代码进行响应，即使出现错误，响应正文中也会包含错误详细信息。

gRPC（Google 远程过程调用）

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

缺点：与 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，从而防止不必要的跨站点交互。