什么是 API 设计？

API 设计包括有关 API 端点、请求和响应格式、协议以及 API 与其他应用程序和消费者通信方式的决策。API 设计在 API 治理中也起着重要作用。

API 治理是指指导组织如何开发、部署和使用 API 的一整套标准、政策和实践。有效的 API 设计能够生成符合这些预定策略的 API，并提供最新的稳健文档来解释 API 的工作原理。结果是精心设计的 API 具有更好的可重用性、可扩展性、兼容性，并为最终用户提供更好的用户体验。

API 用例多种多样，API 设计方法也数不胜数，其中一些协议、架构风格和语言比其他协议、架构风格和语言更适合特定任务或用例。

随着 Web API 使用的增加，它导致了某些协议、风格、标准和语言的开发和使用。这些结构体为用户提供一组参数或 API 规范，定义了可接受的数据类型、命令、语法等。实际上，这些 API 协议促进了标准化信息交换。

常见的协议、架构风格和语言包括：

• SOAP（简单对象访问协议）
• 远程过程调用 (RPC)
• WebSocket
• REST（表述性状态转移）
• GraphQL

为新 API 选择正确的结构是设计过程的一个重要方面。这些协议、架构风格和语言之间并不一定有优劣之分。它们是完成不同任务的不同工具。

SOAP 是一种基于 XML 的轻量级消息传递协议规范，支持端点通过一系列通信协议，包括 SMTP（简单邮件传输协议）和 HTTP（超文本传输协议），发送和接收数据。SOAP 具有独立性，这使得 SOAP API 可以在不同环境中运行或以不同语言编写的应用程序或软件组件之间共享信息。

与其他类型的 API 相比，SOAP API 往往以更正式、更结构化的方式进行开发。SOAP API 自 20 世纪 90 年代以来就已存在；这是一种更古老、更成熟的格式，但也比 REST 等更现代的架构更慢。

SOAP 采用 XML 格式对数据进行编码，不支持其他格式的数据传输。另一方面，SOAP API 不一定需要 HTTP 来传输消息，这使得它们在数据传输方面更加灵活。SOAP 被认为比其他一些协议更安全，因此 SOAP API 适合负责处理敏感数据的系统。

远程过程调用 (RPC) 是一种协议提供操作系统中使用的高级通信范例。RPC 实现了逻辑上的客户端到服务器通信系统专为支持网络应用程序而设计。RPC 协议使用户能够像使用本地过程一样使用远程过程。这使得它们非常适合需要大量客户端/服务器交互的情况。

RPC API 可以进一步细分为 XML-RPC、JSON-RPC 和 gRPC。XML-RPC 是一种使用特定 XML 格式传输数据的远程过程调用。它们甚至比 SOAP API 还要古老，但简单且轻量。JSON-RPC 是使用 JSON（JavaScript 对象表示法）传输数据的远程过程调用。由于 JSON 使用通用数据结构，因此可以与任何编程语言一起使用。

gRPC 是最初由 Google 开发的高性能开源 RPC 框架。gRPC 使用网络协议 HTTP/2 和 Protocol Buffers 数据格式通常用于连接微服务架构中的服务。

WebSocket API 支持客户端和服务器之间的双向通信。这种类型的 API 不需要为每次通信建立新的连接——连接建立后就可以持续进行交换。这使得 Web Socket API 成为实时通信的理想选择。

实时聊天、实时位置跟踪和数据广播都是 WebSocket API 的绝佳用例。WebSocket API 也对数据同步很有用，数据同步是指在多个设备或系统之间保持数据一致和最新的做法，因为它们可以实时更新，而无需每次更改时都创建新连接。

REST 是一组 Web API 架构原则。REST API（又称 RESTful API）是指遵守某些 REST 体系结构约束的 API。REST API 使用 GET、PUT、HEAD 和 DELETE 等 HTTP 请求与资源交互。REST 将数据作为资源提供每个资源由唯一的 URI 表示。客户端通过提供资源的 URI 来请求资源。REST API 是无状态的，它们不会在请求之间保存客户端数据。

RESTful API 之所以流行，是因为它们轻量、灵活且易于使用。它们完全支持不同格式的消息传输，如纯文本、HTML、YAML、XML 和 JSON，并且支持缓存。虽然这使得它们在各种情况下都能发挥作用，但有些站点需要使用更特殊的语言或协议才能高效地完成任务。

GraphQL 是一种查询语言和 API 运行时，由 Meta 公司于 2012 年内部开发，然后在 2015 年开源。GraphQL 支持用户仅用几行代码发出 API 请求而不必访问具有许多参数的复杂端点。此功能可以更轻松地生成和响应 API 查询，特别是针对多个资源的更复杂或特定的请求。

鉴于 Meta 开发这种查询语言是为了提高其移动应用程序的效率，GraphQL API 对移动应用程序有用也就不足为奇。通过提供单一入口点，GraphQL API 无需向服务器发出多个请求即可查询数据，从而缩短加载时间。

API 的设计过程有四个关键阶段：

• 规划
• 开发
• 测试
• 部署

所有这些步骤都需要关键 API 利益相关者之间的协作。尽管某些步骤最适合某些利益相关者，但 API 设计在整个过程中仍然应具有协作性。这有助于开发人员避免添加程序不需要的额外功能，从而加快整体开发进程。

任何项目的第一步都是让每个人都参与到他们正在创建的新 API 类型中。面向公众、供客户在电子商务环境中交互的 API 与面向内部、用于身份验证工作流程的 API 在设计和功能需求上有所不同；在开发开始之前，所有利益相关者必须了解潜在 API 的用例。

了解企业正在构建的什么功能（以及为什么）可以让开发人员更好地了解构建方式，包括使用什么协议。例如，如果这个潜在的 API 需要实时通信，那么开发人员就知道他们在创建时可能会使用 WebSocket，因为该协议非常适合这种用途。

一旦利益相关者对 API 的功能和运作方式有了清晰的认识，就可以开始构建。在 API 开发过程中，开发人员定义 API 端点；设计 API 的数据模型；确保 API 遵守 API 安全策略并返回错误的标准状态码；如有必要，实施 HTTP 标头、API 密钥、OAuth 或 JSON Web 令牌 (JWT) 等身份验证机制；定义错误代码、消息和响应。

开发过程的另一部分是文档编制。在构建 API 时，所有的选择都应记录在一份人类可读和机器可读的文档中。人类可读的文件是用自然、易懂的语言编写的。机器可读文档应遵守 API 规范，例如 OpenAPI 规范，该规范将格式标准化，以使其保持一致，并能够集成到未来的系统中。

API 设计可能是一个高度迭代的过程；特别是当 API 暴露敏感数据时，对其进行严格的错误和缺陷测试就显得尤为重要。制作完成后，最重要的是看它是否按预期运行。测试 API 的一个重要部分是模拟，即创建带有样本数据的模拟服务器，以检查 API 是否能正确与其端点通信并返回预期结果。

模拟可以与 API 测试一起进行。API 测试包括合约测试，即确定请求和响应应该是什么样子；单元测试，用于确认单个端点是否提供预期响应；负载测试（测试 API 是否能够在峰值流量和端到端测试下运行）和端到端测试（验证涉及与多个 API 通信的用户旅程）。测试可以手动完成，也可以通过实施自动化测试框架来完成。

如果一切正常，则 API 就可以发布和部署了。此时，API 文档定稿非常重要，这样其他用户及其机器才能将此 API 正确集成到其计算机网络环境中。一旦 API 发布，用户可能会发现利益相关者没有预料到的问题。在发布 API 之前制定好版本控制策略会很有帮助，这样当开发人员需要更新应用程序时，就可以清楚且一致地更新。

API 优先的应用程序开发方法是指，在软件开发过程开始时优先考虑 API 的设计，并使用将通过 API 交付的服务构建应用程序。其想法是，在软件开发初期就优先考虑 API 的设计，这样开发出来的 API 更可重用、更安全、更高效、更易使用，也更符合组织的目标。这种方法与代码优先方法相反，后者将代码逻辑放在首位，开发人员在后期创建与软件相匹配的 API。

API 设计是 API 优先方法的关键。在 API 优先方法中，API 是应用程序开发的核心，而经过深思熟虑的设计可促进性能更好、更有价值的应用程序。

强大的 API 设计实践还可以在开发和性能问题升级为更大的问题之前发现并解决它们，从而帮助改善开发人员的体验和最终用户的体验。

利益相关者可以从开发过程一开始就确定企业的所有应用程序都能相互集成并良好协作。一旦成功实施，API 优先的方法和全面的文档将使开发人员能够重用现有的 API，而不是重新创建现有的功能。

REST（或 RESTful）API 结构松散。唯一的要求是，它们要符合以下六个 REST 设计原则，也称为架构约束：统一接口、客户端/服务器解耦、无状态、可缓存性、分层系统架构以及可选的按需编码。

这些架构限制使得 RESTful API 非常适合 API 优先的方法：客户端/服务器解耦和无状态性尤其有帮助。

在 RESTful API 中，客户端和服务器应用程序必须相互独立。客户端应用程序应该知道的唯一信息是所请求资源的统一资源标识符 (URI)，它不能以任何其他方式与服务器应用程序交互。

REST API 也是无状态的，这意味着每个请求都需要包含处理它所需的所有信息。换言之，REST API 不需要任何服务器端会话。这些限制使这些 API 独立于企业的服务器，使其具有灵活性——客户端和服务器端应用程序可以使用不同的语言和协议编写，而不会影响 API 的设计。

RESTful API 也非常适合 API 优先的环境，因为它们是可扩展和轻量级的。客户端和服务器之间的分离提高了可扩展性，因为 RESTful API 不需要保留过去的客户端请求信息，从而减少了通信瓶颈。有效的缓存还可以减少客户端/服务器交互，这对于可扩展性来说又是一个优势。由于 RESTful API 使用 HTTP 格式进行消息传输，因此可以接受多种格式的数据传输。这样可以简化与新环境的集成。

微服务架构是一种云原生架构风格，在这种方法中，单个应用程序由很多松散耦合并能够独立部署的更小组件或服务组成。REST API 通常用于实现这些较小服务之间的通信。

API 优先的方法与微服务架构模式相得益彰，因为 API 是用来将服务连接在一起的。如果 API 设计是组织的首要任务，并且 API 设计可以相互无缝通信，那么开发人员就可以将这些服务打包到更大的应用程序中，同时节省时间。

为了从企业 API 中获得最大价值，组织通常强调：

• API 治理与文档
• 收集利益相关者的反馈
• 适当的身份验证
• 版本控制
• 错误信息标准化
• 规模和背景
• 一致性

这些原则有助于让所有利益相关者了解整个 API 设计过程，并确保 API 与组织目标和战略保持一致。

API 治理和文档：尽早创建全组织范围的 API 管理和文档策略有助于促进一致性，并使企业的 API 组合更易于浏览。例如，组织可能会选择采用诸如 OpenAPI 之类的规范，以便所有企业 API 都遵守行业范围的标准。无论如何，保持适当和一致的管理和文档，能让新的 API 用户快速了解 API 及其功能。

收集利益相关者的反馈： 核心利益相关者的早期反馈有助于开发人员在整个开发过程中保持正确的方向。沟通不畅会导致 API 开发延误，并降低 API 的价值。

适当的身份验证和 API 安全：为了保护 API 以及敏感数据，企业应采用验证技术，对 API 请求进行验证。API 密钥、OAuth 和 JSON Web 令牌 (JWT) 等身份验证机制提供了不同的方法来确保数据和 API 流量的安全。API 加密是对客户端和服务器之间传输的数据进行编码的过程，也用于保护数据和 API。

测试和版本管理： API 测试包括正反两方面的各种情况，以便在部署 API 之前发现问题。在测试过程中， API 会不断开发，开发人员会创建新版本来修复错误或提高性能。还会出于其他原因发布新的 API 版本，例如开发人员向 API 添加新功能。版本控制是开发人员管理 API 变更、使变更透明化并确保更新不会干扰当前用户的方式。

在真正开始开发之前，定义版本机制（如基于 URL 的版本机制或基于页眉的版本机制）是很有帮助的。

错误消息标准化：正确的错误处理可改善 API 用户的体验，因为它有助于在出现问题时排除故障。错误代码、消息和响应需要准确描述错误的性质，并保持清晰和一致。

背景和限制：每个 API 都存在于特定的背景中，这种背景决定了它的构建方式和功能。相互竞争的项目期限、预期流量以及企业是 API 优先还是代码优先，都会影响最终的 API。所有利益相关者都应该了解这些信息，以便在开发过程中做出明智的决策。

一致性：最重要的是，保持一致性通常能让 API 设计更出色。API 设计的一致性不仅仅是版本和错误代码。在定义端点时，保持命名规则的一致性可以使端点更容易识别。向 API 发出特定请求时，每次都应以相同的方式解析。当 API 环境中的所有元素都保持一致时，也更容易编写 API 文档，以便未来的用户能够理解。