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

在本次深入探讨中，我们将从基础知识入手，介绍 API 的设计，并进一步介绍定义卓越 API 的最佳实践。

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

API 设计：电子商务示例

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

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

API 设计和 CRUD：

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

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

例如，要添加一个新产品（创建），您需要向 /api/products 发送一个 POST 请求，在请求体中发送产品详细信息。

要检索产品（读取），则需要从 /products 发送 GET 请求获取数据。

要更新产品信息（更新），我们需要向 /products/:id 发送 PUT 或 PATCH 请求，其中 id 是我们需要更新的产品的 id。

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

通信协议和数据传输机制

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

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

API范式

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

REST（表征状态传输）

优点：客户端向服务器发出的每个请求都必须包含理解和完成请求所需的全部信息。使用标准 HTTP 方法（GET、POST、PUT、DELETE）。便于不同客户端（浏览器、移动应用程序）使用。

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

特点是支持分页、过滤（限制、偏移）和排序。使用 JSON 进行数据交换。

GraphQL

优点允许客户端准确请求所需内容，避免过度抓取和抓取不足。基于模式的强类型查询。

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

特点通常以 HTTP 200 状态代码响应，即使出现错误，也会在响应正文中提供错误详细信息。

gRPC（谷歌远程过程调用）

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

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

特点是支持数据流和双向通信，是服务器到服务器通信的理想选择。

API设计中的关系

在电子商务环境中，可能存在用户与订单、订单与产品等关系。

设计端点来反映这些关系非常重要。例如，在这种情况下，GET /users/{userId}/orders 应获取特定用户的订单。

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

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

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

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

向后兼容性和版本控制：

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

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

就 GraphQL 而言，在不删除旧字段的情况下添加新字段（v2 字段）有助于在不破坏现有客户端的情况下发展应用程序接口。

速率限制和 CORS

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

常见做法是同时设置 CORS 设置 跨源资源共享（CORS）设置对网络安全非常重要。它们可以控制哪些域可以访问您的应用程序接口，防止不必要的跨站交互。

原文链接：API design 101 from basics to best practices