什么是 API（应用程序编程接口）？

API 只公开某次交互所需的数据和功能，把其他内部实现细节隐藏起来。这种抽象保护了系统的完整性，也简化了软件组件之间的通信方式。

API 有很多种——硬件和固件 API、操作系统 API、库和框架 API、Web API 等等，但从宏观层面看，它们的运作方式都一样：定义两个软件之间的契约，规定可以请求什么、返回什么。

作为一篇以集成为中心的解读文章，本文重点讨论 Web API（一种让软件能够通过网络发出请求的 API，通常使用 HTTP），包括它们的工作原理、彼此的差异，以及如何用它们来连接系统、同步数据和自动化工作流。

把 API 通信理解为客户端与服务器之间的一问一答，会很有帮助。提交请求的应用是客户端，提供响应的是服务器，而 API 定义了两者之间的通信规则。

举个简单的例子：第三方支付处理。当用户在电商网站上购买商品时，网站可能会提供“使用 PayPal 付款”的选项。这个功能就依赖 API 来建立连接。

• 当买家点击付款按钮时，就会发起一次 API 调用。该请求通过 API 的统一资源标识符 (URI) 从应用发送到 Web 服务器，其中包含请求动词、标头，有时还有请求正文。这些信息共同指定了请求的内容以及请求方式。
  
  
• 收到客户端的有效请求后，API 会把请求转发给外部程序或 Web 服务器（在本例中就是第三方支付系统），并返回带有所请求信息的响应。
  
  
• API 将数据传输到初始请求的应用程序，此处为产品网站。

对最终用户来说，这整个交互过程是不可见的——他们看到的只是一条付款成功的确认信息。

API 存在于软件的每一层，从贴近硬件的那一层，一直到大多数人每天都在打交道的 Web 服务。在很多日常交流中，API 被当作 Web API 的同义词来使用。但服务不同用例的 API 其实有很多种，包括：

• 硬件和固件 API 让软件能够与设备的物理部件（如处理器和传感器）通信。
  
  
• 操作系统 API 让软件能够与操作系统通信，以获得文件、进程和内存管理等服务。
  
  
• 库和框架 API 会公开预先写好的代码（函数、方法和钩子），开发者可以直接在自己的应用里调用，无需经过网络。
  
  
• 数据库 API 软件能够与数据库中存储的信息通信，并对其进行操作和提取。
  
  
• Web API 让软件能够通过网络发出请求，通常使用 HTTP。它们属于远程 API，用于促进不同机器之间的通信和资源操作，而不是单台设备内部。

*值得注意的是，一些较老的系统直接把 FTP、SMTP 和 SSH 等网络协议作为自己的集成接口暴露出来。从技术上讲，它们符合 API 的宽泛定义，只不过它们按通信方式分类，而不是按对接对象分类，与以集成为中心的讨论关系不大。

Web API 在集成中最为常见。与上面列出的其他 API 类型不同，它们专为不同应用之间通过网络通信而设计。

REST 是当今 Web API 的主流架构风格。REST API 也称为 RESTful API，遵循 Roy Fielding 首次提出的六项指导性架构约束，用于构建可扩展、灵活且解耦的 Web 服务。

REST 把数据作为资源提供出来，REST API 则使用 GET、POST、PUT、PATCH 和 DELETE 等 HTTP 方法与这些资源交互。每个资源都由唯一的 URI 标识，通常称为 API 端点。这就是客户端发送 API 请求的具体地址。

REST 由以下约束定义：

• 统一接口——创建标准化的通信规则：对同一资源的所有请求，形式都应该一致。每个资源都应只对应一个 URI。
  
  
• 客户端/服务器分离——客户端和服务器应用必须能够各自独立演进，互不依赖。客户端掌握的唯一信息就是资源的 URI。
  
  
• 无状态性——服务器不在请求之间保存会话状态。每个请求都是自包含的，必须携带处理它所需的全部信息。
  
  
• 可缓存性——所有资源都应尽可能可缓存，并且服务器必须声明这些资源可缓存。
  
  
• 分层系统架构：由于 REST 中的每个请求都是自包含的，客户端无需知道自己在跟源服务器通信，还是跟某个中间层通信。这让 REST 非常适合为众多客户端提供服务的公共 API。
  
  
• 按需代码（可选）：REST API 通常返回数据。这最后一项约束（也是唯一的可选约束）允许返回可执行代码，例如 JavaScript，供客户端在需要时运行。

想了解 REST 原则更完整的说明，请访问此处。

SOAP 是一种基于 XML 的消息协议，对消息的结构和传输方式有严格标准。与实际上几乎只跑在 HTTP 上的 REST API 不同，SOAP 与传输协议无关。它可以运行在 HTTP、SMTP 和其他协议之上，在 HTTP 并不总是底层协议的企业环境中更加灵活。

SOAP 消息有严格的报文结构，规定了消息该如何处理，这使得 SOAP 比 REST 更冗长，但也更标准化。SOAP 的正式标准、内置错误处理机制和严格的安全规范至今仍有价值，也推动着它在金融、医疗等行业继续被使用。

RPC 出现得比 Web API 更早，既有传统实现，也有现代实现。RPC 有时也被称为子程序调用或函数调用，它让应用能够像调用本地函数一样，在远程服务器上执行某个函数或方法。RPC 是围绕操作而非资源来组织的。RPC API 通常不会为每个资源各设一个 URI，而是公开单一端点，把要执行的操作写在请求有效载荷里。

XML-RPC 是 JSON-RPC 的直接前身，它用 XML 来编码调用和响应。它比 SOAP 更早出现，但更简单，因此更容易实现，尽管 XML 的冗长让它比基于 JSON 的替代方案更重。它本质上就是 JSON-RPC 的直接祖先。

JSON-RPC 的工作方式与 XML-RPC 相同，只是用 JSON 取代了 XML。JSON 比 XML 更紧凑、更易于解析，这让 JSON-RPC 比它的前身更轻量、更易读。

gRPC 是 RPC 家族中现代的高性能方案。它最初由 Google 开发，现在作为一个开源项目进行维护。早期的 RPC 实现采用基于文本的格式，而 gRPC 使用 Protocol Buffers（或 Protobuf）——一种二进制序列化格式，能生成比 JSON 或 XML 更小、更快的消息。

它还运行在 HTTP/2 而非 HTTP/1.1 之上，从而带来进一步的性能优势。gRPC 常用于内部微服务之间的通信，并支持双向流式传输，是实时数据流的理想选择。

GraphQL 是 Facebook 于 2012 年开发的一种开源查询语言和服务器端运行时，目的是让资源获取更高效。它的设计目标是消除过度获取（拿到超出需要的数据）和获取不足（需要多次请求才能拿到所需数据）的问题，办法是让客户端精确指定自己想要哪些数据。GraphQL 使用单一端点，客户端可以通过它查询多个资源，并在一次响应中返回结果。

GraphQL 虽然非常灵活，但比 REST 复杂，多用于各个客户端数据需求差异很大的复杂环境。

点击此处阅读 REST 与 GraphQL 更深入的对比。

上述 API 都遵循由客户端发起的请求/响应模型。在集成语境下，有两个值得注意的重要例外：

• WebSockets (WebSocket API) 会维持一条持久的双向连接，适合实时数据源这类实时用例。
  
  
• Webhook 则彻底颠覆了这个模型：不是由客户端发起请求，而是在特定事件发生时由服务器向客户端推送通知。

公共 API 完全开放到互联网上，任何开发者或组织都可以使用，通常没有限制或限制极少。开发者可能需要获取一个 API 密钥，除此之外，使用这些 API 几乎没有别的门槛。它们的设计初衷就是鼓励外部集成和第三方开发。

*请勿与“OpenAPI 规范 (OAS)”混淆，点击此处可了解更多信息。

私有 API 不对公众开放，只能在特定组织内部访问。它们通常隔离在私有网络中，访问时需要严格的身份验证。组织通常用这类 API 来连接内部软件系统。

从访问角度看，合作伙伴 API 介于公共 API 和私有 API 之间：它们面向一组特定的授权业务合作伙伴开放。尽管可以通过公共互联网访问，但它们并不对公众开放，访问权限只授予经过授权的用户。合作伙伴 API 用于 B2B 数据共享或数据流变现等场景，其使用通常受具体的合作伙伴协议约束。

*复合 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 视为应用的基础，在编写任何应用代码之前先把它设计出来。组织不是从后端业务逻辑和数据库结构入手，而是先定义契约（通常使用 OpenAPI 这类 API 规范），再围绕它构建应用的其余部分。

对于集成密集型的组织，这是优先选择的方法，因其可扩展性、可靠性和一致性而备受青睐：API 是唯一可信来源，所有使用方（Web 和移动应用、物联网 (IoT) 设备、AI 应用与模型，以及其他系统）都与同一 API 层交互，而不是各自做定制集成。

有些组织把 API 设计优先和 API 优先视为两种不同的方法，后者是更宽泛的、覆盖整个组织的职能：把 API 本身当作产品来管理，有自己的生命周期、产品经理和路线图。

微服务是一种架构风格，它把一个应用拆分成更小、更独立的服务。这些服务之间通过 API 通信，协议和风格往往是混用的：例如面向外部的服务用 REST API，内部服务间通信用 gRPC，事件驱动的流程用 Webhook。微服务架构让开发者可以灵活地为某个具体服务挑选最合适的框架。

它还让开发者能够彼此独立地测试、部署、更新、集成、维护和扩展各个服务。故障隔离变得简单——单个组件出故障不会让整个应用崩溃；而且由于服务之间是松耦合的，内部实现可以在不破坏集成的前提下进行更改。

微服务的一个常见问题是所谓的“前端频繁调用”问题。在传统应用中，数据都放在一个数据库里，客户端一次调用就能查到。而在微服务架构下，数据分散在许多服务中，客户端可能需要通过几十个单独的请求，跟几十个服务打交道，才能拿到所需的数据。复合 API 通过提供一个统一的端点来解决这个问题：这个端点充当编排层，接收客户端请求，与各个后端服务通信以收集所需数据，然后在单个有效载荷中把结果返回给客户端。

复合 API 让客户端不必为了一个操作而反复往返调用多次。它们还隐藏了系统内部的复杂性：客户端不需要知道哪个微服务掌管哪些数据，只需知道怎么访问这个复合端点。而且它们还能降低延迟，因为依赖内部微服务通信的一次调用，通常比经由外部网络的多次往返调用要快。

微服务架构虽有种种好处，但也扩大了 API 覆盖面、增加了复杂性，凸显出强有力的 API 管理有多重要。

API 管理是指在 API 的整个生命周期内对其进行发布、保护、控制和监控的过程。这项工作通常通过 API 管理平台来集中完成，该平台可帮助组织在所有 API 上执行一致的策略。这些平台中有不少还包含设计和文档工具，不过本节重点讨论 API 管理在运营层面的作用。

API 管理包括对以下方面的监督：

API Gateway 是一个软件层，为客户端提供访问多个后端服务的统一入口。它让客户端不必去理解或应对网关背后的架构复杂性，也用于遏制微服务带来的 API 泛滥。

其主要功能包括路由、身份验证、速率限制和监控。Gateway 还可以处理请求聚合，因此常被用来实现复合 API。

API 安全是一套实践与流程，用于保护 API 及其传输的数据免受滥用、恶意机器人攻击和其他网络安全威胁。API 安全包括身份验证（确认用户身份）、授权（确定用户可执行的操作）、加密、输入验证等。常见的安全技术包括用于身份验证的 API 密钥和 OpenID Connect (ODIC)，以及用于授权的 OAuth。良好的 API 安全态势有助于确保只有经过授权的用户和应用才能访问 API。

速率限制和节流用于控制 API 请求的数量和流量，帮助系统保持稳定可用。速率限制会限制单个客户端在指定时间段内可以发起的调用次数，而节流则管理系统接受的调用量，通常的做法是放慢请求速度或让请求排队。速率限制还有商业上的作用，使组织能够为付费 API 执行不同的用量档位。

尽管它们主要是运维层面的考量，但速率限制和节流都还发挥着次要的安全作用，有助于阻止拒绝服务攻击和凭据填充攻击。

API 管理负责落实设计阶段制定的版本管理策略。管理平台让组织能够把流量路由到正确的 API 版本，同时运行多个版本，并管理旧版本的弃用。这让团队可以推出更新和新版本（哪怕是破坏性变更），同时给现有集成留出时间，在不中断的情况下完成迁移。

API 是企业系统、服务与合作伙伴之间的连接纽带，了解它们的运行状况至关重要。一个 API 出故障，可能会让所有依赖它的集成都出问题；监控与可观测性能帮助团队在问题扩散到互联系统之前就发现并诊断它们。

API 监控会跟踪 API 的性能、可用性、功能和使用情况，并在延迟或错误率等指标超出预定义阈值时发出告警。可观测性在监控的基础上更进一步，借助指标、日志和链路追踪更深入地了解系统健康状况，并呈现监控没有标记出来的信息。

了解 API 的使用情况，有助于团队规划容量、应对潜在威胁，并遵守政府与监管要求。

API 把软件应用、系统和工作流连接起来，以交换数据和服务，这一功能通常称为 API 集成。在大多数现代集成中，API 是信息在服务与系统之间流动的核心。

常见的企业用例包括：

API 让团队能够把第三方服务集成到自己的应用和工作流中。例如，一家辣酱公司想在自己的网站上放一张门店定位地图，展示合作零售商，就可以调用某个地图应用的 API，把这些信息嵌入自己的站点。

组织通过 API 与合作伙伴、供应商和客户共享数据和服务。物流公司可以用 API 把订单跟踪信息公开出来，让零售商把它接入自己的系统。

组织用 API 促进企业系统之间的数据交换，例如客户关系管理 (CRM) 和企业资源规划 (ERP) 平台之间的交换。如果 CRM 平台中更新了某个客户地址，这一变更可以自动传播到所有相连的系统。

API 用于访问大语言模型 (LLM) 和机器学习模型等 AI 工具，并将其集成到应用和工作流中。集成 AI 模型的方式与其他第三方集成类似：团队不必在内部从头构建和训练一个复杂模型，而是可以通过 API 去访问外部模型。

AI 智能体也使用 API 来访问服务、完成任务，但它们的工作方式不同于传统的集成：后者由开发者事先决定调用哪些 API 以及怎么调用。AI 智能体是在运行时做出这个决定的，而且必须能够自由地分析问题、选择工具并即时探索解决方案。它们需要一种一致的方式来发现工具并了解如何使用这些工具。

模型上下文协议 (MCP) 是由 Anthropic 提出、现由 Linux 基金会管理的开源标准，它把 AI 模型和智能体与外部应用和系统连接起来，填补的正是这块空白。MCP 服务器通常架在现有 API 之上，充当“通用翻译器”，以标准化的方式描述某个工具的能力，供任何兼容 MCP 的 AI 应用使用。开发者不必在每一个 AI 应用和每一个工具之间都做一套定制集成，只需为某个工具构建一个 MCP 服务器，就能让它对所有兼容的智能体开放。MCP 常被比作 AI 应用的 USB-C 接口：只用一个标准连接器，取代大量定制连接器。

移动应用和 Web 应用通过 API 与后端通信，取回数据或触发操作，而完全不直接访问数据库或业务逻辑。组织可以只构建一次后端功能，再用 API 同时服务 Web、iOS 和 Android 客户端。这样无需重建后端，就能增加新的渠道。

有些组织更进一步，采用服务于前端的后端模式：在共享 API 之上叠加一层轻薄的客户端专属层，同时把核心业务逻辑集中在一处。

有些应用等不及客户端来请求信息。实时 API 和事件驱动型 API 把这种关系翻转过来：信息一变化或某个特定事件一发生就主动推送，而不是等客户端反复来请求更新。

Webhook 在特定事件发生时通知已连接的系统，而 WebSocket 和 gRPC 流式传输则为持续的数据流保持长连接。它们共同支撑着金融交易平台、聊天系统、多人游戏和 IoT 传感器数据交换，无需不断轮询就能让系统保持最新状态。