API 手册：您必须了解的每种类型

Source: Dev.to

如果你曾经好奇为什么你最喜欢的应用程序似乎能神奇地相互通信——比如 Google Maps 能出现在共享出行应用中——那你已经看到 API 的实际运作了。API（应用程序编程接口）的本质就是一套规则，允许不同的软件应用之间进行沟通和数据交换。

可以把它想象成一个翻译官，帮助说不同语言的两个人进行对话。在数字世界里，API 就是软件之间的翻译官。本指南将通过简单的类比，带你了解七种最常见的 API 类型，帮助你理解每种类型的独特之处以及何时使用它们。

1. REST API – 通用服务员

REST API 是当今网络上最常见、最灵活的 API 类型。

类比： 把 REST API 想象成餐厅里的服务员。你（你的应用）告诉服务员你想要点什么菜单，服务员去厨房（服务器）取来，然后送回给你。

“REST” 的含义： 表述性状态转移（Representational State Transfer）——一种正式描述应用在互联网上进行简单、标准通信的方式。

关键特性

• 使用标准的 HTTP 方法——与网页浏览器使用的相同简单、熟悉的操作，使开发者直观易懂。

  方法	用途	示例
  GET	检索数据	“显示这个用户的个人资料。”
  POST	创建新资源	“添加这个新用户。”
  PUT	更新已有数据	“更新这个用户的电子邮件。”
  DELETE	删除数据	“删除这个用户。”

• 无状态——每个请求都是完全独立的。服务器不会记住之前的请求，这简化了系统，并且能够在不产生混乱的情况下同时处理数百万用户。

• 平台无关（JSON）——REST 通常使用 JSON（JavaScript 对象表示法），一种简洁的文本数据格式。这使得任何类型的应用——无论是 iPhone、Android 还是网站——都可以使用同一个 API。

何时使用： 非常适合构建通用应用，例如需要获取用户资料和发布动态的社交媒体应用。

注意： REST 极其灵活且流行，但在需要高安全性和严格规则的场景（例如银行转账）下，可能需要更结构化的方法。

2. SOAP API – 正式商务合同

在 REST 成为标准之前，SOAP 是企业级通信的主流选择。

类比： 如果 REST 像一次随意的电话，SOAP 则像一份正式的商务合同。每条消息都必须遵循严格的规则，并以非常特定的结构包装。

“SOAP” 的含义： Simple Object Access Protocol —— 一种较早、更正式的通信方式，要求所有消息都采用严格的基于 XML 的结构，包含信封、头部和主体。

关键优势

• 协议无关 – 虽然 SOAP 常使用 HTTP（如同 REST），但它并不局限于此。它也可以在其他协议上运行，如 SMTP（电子邮件），在某些企业环境中提供了灵活性。

• 内置标准 – SOAP 包含行业标准的安全、错误处理和事务规则。这使得它在对精确性和可靠性要求极高的系统中极受信任。

典型使用场景： 银行、医疗机构和政府系统仍然大量依赖 SOAP。例如，当你在银行之间转账时，背后很可能运行着 SOAP API，以确保交易的安全和正确处理。

注意事项： 虽然 SOAP 提供了企业级的可靠性，但现代应用常常需要原始的速度和性能，这促使了高性能替代方案的出现。

3. gRPC API – 一级方程式赛车

由 Google 开发，gRPC 是一种从头开始构建以实现最高速度和效率的 API。

类比： 将 gRPC 视为 API 领域的一级方程式赛车——专为速度、性能和精确度而生。

“gRPC” 的含义： 现代的高性能版 RPC（Remote Procedure Call，远程过程调用）。RPC 允许应用程序像调用本地函数一样跨网络调用另一台机器上的函数。gRPC 为当今大规模、实时应用完善了这一概念。

为什么它如此快速

• Protocol Buffers（Protobuf） – 与 REST 使用基于文本的 JSON 不同，gRPC 使用 Protocol Buffers，这是一种紧凑的二进制格式，可压缩数据，使处理和传输速度大幅提升。

• HTTP/2 – gRPC 基于 HTTP/2 运行，允许多个请求共享单个连接并行进行，显著提升效率。

• 高级通信模式 – 除了简单的请求‑响应，gRPC 还支持：

  • 服务器流式 – 从服务器向客户端实时推送更新。
  • 客户端流式 – 客户端持续向服务器发送数据。
  • 双向流式 – 双方实时“聊天”。

性能提升巨大；gRPC 往往比同等的 REST API 快 7–10 倍。正因如此，它为 Netflix、Uber 等公司提供性能关键的系统支撑。

最佳场景： 速度至关重要的服务器间通信。

4. GraphQL API – 精准购物者

由 Facebook 创建，GraphQL 是一种革命性的获取数据方式，解决了开发者在使用 REST API 时常见的困扰。它的主要目标是防止 过度获取（获取了太多数据）和 不足获取（数据不足，需要多次请求）。

类比： 使用 GraphQL 时，你就像一个购物者，向店员准确说明想要的商品，店员只会把这些商品送回来——既不多也不少。

工作原理

你编写 一个查询，精确请求所需的数据；单一端点处理该请求，并每次返回恰好的数据。

关键特性

• 精准数据获取 – 只请求用户的用户名和电子邮件，而不获取其完整资料，节省带宽并提升移动应用的速度。
• 自描述 – GraphQL API 自带内置的“playground”，让开发者即时探索可用数据并测试查询，使其使用极其简便。
• 实时订阅 – 允许应用程序自动监听实时数据更新，服务器可以在数据变化时即时推送给客户端。

像 GitHub 和 Shopify 这样的主要科技公司已经在 GraphQL 上构建了完整的 API，因为它为前端开发者提供了所需的灵活性和效率。

5. WebHook API – 门铃通知

WebHook 完全颠覆了传统 API 的通信模型。

• 传统 API – 您的应用不断检查它的“邮箱”：您走到外面，打开它，看到空的，然后走回去。
• WebHook – 就像邮递员在信件到达的瞬间按响您的门铃——即时、直接且高效。

WebHook 常被称为 “反向 API”，因为它不是让您的应用轮询服务器获取新信息，而是服务器在特定事件发生的瞬间 推送 信息到您的应用。

工作原理

1. 您从应用向另一个服务提供一个 回调 URL。
2. 当该服务上发生您关心的事件时，它会自动向您的 URL 发送一个 POST 请求，携带事件详情。
3. 无需轮询，无需浪费请求——实时更新。

常见使用场景

• GitHub 在有新代码推送时触发 WebHook。
• Shopify 在创建新订单时触发 WebHook。
• Slack 和 Discord 机器人依赖 WebHook 来响应指令。

WebHook 在基于事件的通知方面表现出色，但若需要持续的、双向的对话，则需要保持永久打开的连接。

6. WebSocket API – 开放电话线

WebSocket 旨在实现持久、实时、双向通信。

• 可以把 WebSocket 想象成在你的应用与服务器之间开通一条永久的电话线。
• 一旦连接建立，双方随时都能即时互相通信。

握手

1. 客户端发送一个特殊的 HTTP 请求，称为握手，请求服务器升级连接。
2. 服务器同意后，从此刻起就打开了一条持久的双向通道。

不同于传统 HTTP 必须由客户端始终发起请求，WebSocket 允许服务器随时向客户端推送数据。该协议灵活多样——你可以发送纯文本、JSON，甚至是二进制文件（如图片、视频）。

理想的使用场景

• 实时聊天消息
• 实时股票价格更新
• 实时游戏事件和计分板

WebSocket 为你在网页上体验的许多即时、交互式功能提供动力。它们建立了强大的客户端‑服务器连接，但如果你想完全绕过服务器，直接让两个用户之间进行更快的通信，该怎么办？

Source: …

7. WebRTC API – 直接点对点通话

WebRTC（Web 实时通信）实现了 浏览器之间的直接通信。虽然服务器可以帮助浏览器最初相互发现，但实际的数据——视频、音频和文件——是 在用户之间的点对点连接中直接传输 的。

• 当你进行视频通话时，你的视频和音频会直接从你的设备发送到对方的设备——没有服务器在中间存储或处理你的私人对话。
• WebRTC 自动处理所有繁杂的网络细节，使浏览器能够直接找到并连接彼此，从而实现更快的通信，避免服务器瓶颈。

它的应用

• 视频和音频通话（例如 Google Meet）
• 屏幕共享
• 在线游戏
• 即时点对点文件传输

在幕后，WebRTC 使用 自适应比特率流 等特性，依据你的网络速度不断调整视频质量，以确保流畅体验。它为浏览器内的实时通信提供了骨干，无需额外软件。

一目了然 – 七种 API 类型快速比较

结论

没有单一的“最佳”API。每种类型都是为了解决特定问题而设计的。REST API 是一种通用且多功能的工作马，适用于一般用途，但它无法提供 WebHook 的实时推送通知，也达不到 WebRTC 的点对点速度。了解每种 API 的优势和劣势，能够帮助你为任何任务选择合适的工具。

通过学习这些核心概念，你已经迈出了理解现代数字世界构建方式的重要一步。随着你在开发者或技术爱好者之路上的继续前行，你将能够为任何挑战挑选合适的 API 类型。