API 定义API 入门指南

你每天使用 API 数十次，却未曾察觉。用手机查看天气、发送消息、在线支付：每一个动作都在悄悄地向 API 发出请求并等待响应。这个词听起来像是深层基础设施的东西，但背后的理念其实很简单，一旦你理解了，就会发现 API 无处不在。

本指南用通俗语言和技术术语为你给出 API 的工作定义，然后逐步讲解 API 实际如何传输数据：请求与响应、端点、方法、认证以及它们返回的 JSON。之后我们将介绍你会遇到的主要风格（REST、SOAP、GraphQL 和 webhooks），看几个真实示例，并展示爬取 API 如何将一个没有官方接口的杂乱网站变成你可以像调用 API 一样调用的东西。

API 定义：API 究竟是什么

API 是 Application Programming Interface（应用程序编程接口）的缩写，是一套允许两段软件相互通信的规则。一个程序请求某些东西，另一个程序以可预期的格式作出响应。API 就是中间达成的契约，规定了如何发出请求以及你将获得什么回复。

理解它的经典方式是把它比作一家餐厅。你坐在桌子旁（你的应用），阅读菜单上你被允许点的东西（API 的文档选项），然后告诉服务员你想要什么。服务员（API）把你的订单带到厨房（服务器），等菜做好后把结果带回你的桌子。你永远不会走进厨房，也不需要知道菜是怎么烹饪的。你只需要知道菜单上有什么以及如何点单。

从技术角度来说，API 向外部暴露对系统数据或功能的定义接口，同时隐藏其背后的实现。它将数据库、业务逻辑和内部代码抽象化，向外部世界提供一套稳定的可调用操作。这种抽象本身就是全部价值所在：厨房可以完全改变菜谱，只要菜单保持不变，你的桌子永远不会察觉到变化。

API 的工作原理：请求与响应

几乎所有 API 都运行在同一个简单循环上：客户端发送请求，服务器返回响应。其他一切都是这个模式之上的细节。逐一了解这些组成部分，本文的其余内容便会自然而然地融会贯通。

请求

请求是你的程序向 API 发送的消息，说明它想要什么。一个典型的 Web API 请求携带四样东西：要访问的地址（端点）、你想要执行的操作类型（方法）、你的身份（认证），以及有时还会携带你一并发送的数据主体。

响应

响应是返回的内容。它通常包含一个状态码，告诉你操作进行得如何（200 表示成功，404 表示未找到，401 表示未授权），以及包含你所请求数据的主体，通常以 JSON 格式呈现。你的代码读取该响应并对其做一些有用的处理。

端点

端点是你调用的特定地址，用于访问特定资源或操作。如果 API 是菜单，那端点就是菜单上的各个菜品。天气 API 可能公开一个用于当前状况的端点和另一个用于五天预报的端点。端点通常归于几种常见形式：

• 资源端点返回特定的东西，例如单个用户资料或某一件商品。
• 集合端点返回一组东西，例如所有商品的列表。
• 操作端点执行某项操作，例如处理付款或发送电子邮件。
• 搜索端点允许你查询和过滤，例如查找本周下的所有订单。

方法

方法告诉 API 你打算对端点做什么。Web API 直接借用 HTTP 的这些动词，其中四个涵盖了你将编写的绝大多数内容：

• GET 读取数据但不改变任何内容（获取用户资料）。
• POST 创建新内容（提交新订单）。
• PUT 更新现有内容（编辑用户资料）。
• DELETE 删除某些内容（取消订单）。

认证

大多数有用的 API 在响应之前需要知道是谁在调用它。认证是 API 在门口核查你身份的过程。最简单的形式是 API 密钥，一个你随每次请求携带的长保密字符串，用于识别你的账户，就像一把只能开一扇特定门的房门钥匙。Token 更进一步：它们更像一张智能卡，还携带有关你被允许做什么的信息，而 OAuth 2.0 等标准使用它们来实现更丰富的、具有权限意识的访问。正确的选择是在两者之间取得平衡。对于简单的内部工具，基本 API 密钥就足够了，而面向公众的用户应用通常需要 Token 和 OAuth 提供的更强保证。

JSON：大多数响应使用的格式

当 API 响应时，它必须对数据进行格式化，以便你的程序能够可靠地读取。JSON（JavaScript Object Notation）已成为默认格式，因为它紧凑、人类可读，并受每种现代语言支持。它将数据表示为键值对和嵌套列表，与大多数程序已经使用的对象完美对应。单个用户的小型 JSON 响应可能如下所示：

{
  "id": 42,
  "name": "Ada Lovelace",
  "email": "[email protected]",
  "active": true
}

将各部分整合在一起，一次完整的往返请求读起来几乎像一句话：发送 GET 请求，到 users 端点，携带你的 API 密钥，然后获取 JSON 响应。这是同样想法的一行命令，你可以从终端运行，以及它返回的响应类型。

# GET a user, sending an API key as a header
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.example.com/users/42"

服务器读取请求，确认密钥，查找用户 42，并返回上面的 JSON 对象。这就是你将接触到的绝大多数 API 背后的全部机制。

API 类型：REST、SOAP、GraphQL 和 webhooks

API 遵循几种常见风格。它们都执行请求-响应的工作，但在严格程度、数据请求方式以及数据返回方式上有所不同。四种风格覆盖了你会遇到的绝大多数情况。

REST

REST（Representational State Transfer，表述性状态转移）是现代网络上的主流风格。它与其说是严格的协议，不如说是一套约定：在命名清晰的端点上使用普通 HTTP 方法，保持每个请求自包含，并以 JSON 等简单格式返回数据。REST 之所以流行，是因为它易于上手且是无状态的，这意味着每个请求携带服务器所需的一切，服务器不保留对先前调用的记忆。这使 REST API 易于缓存、易于扩展和易于学习，这就是为什么你遇到的大多数公开 API 都是 RESTful 的。

SOAP

SOAP（Simple Object Access Protocol，简单对象访问协议）是更古老、更严格的同类。在 REST 灵活的地方，SOAP 执行严格的契约：消息始终是 XML 格式，必须遵循正式结构。这种严格性在受监管的高风险环境中是一个优势。SOAP 为安全性、事务和可靠性提供了强大的内置标准，因此它仍然出现在银行和支付处理等企业环境中，在这些环境中，有保障的、可审计的消息传递比便利性更重要。

GraphQL

GraphQL 于 2012 年在 Facebook 开发，采用了不同的角度。它不是许多各自返回固定数据形状的端点，而是公开单个端点，让客户端精确请求它想要的字段。其带来的好处是直接的：你不再过度获取不需要的数据，可以在一次往返中获取相关内容而无需多次请求，类型化的模式在你发送任何查询之前就精确记录了可用内容。这种精确性使 GraphQL 对于有许多屏幕（每个屏幕都需要略微不同的同一数据切片）的复杂应用很有吸引力。

Webhooks

Webhooks 颠覆了通常的方向。在 REST、SOAP 和 GraphQL 中，你的应用提问，服务器回答；而在 webhook 中，服务器在事件发生的那一刻通知你的应用，无需提问。你注册一个 URL，当事件发生时（付款到账、构建完成、表单提交），服务会向你的 URL 发送一个包含详情的请求。可以把它想象成：与其反复打电话给厨房询问你的菜是否准备好，不如厨房在菜好了时直接敲铃。Webhooks 是无需反复轮询 API 即可获取实时更新的标准方式。

真实世界的 API 示例

让 API 定义真正落地的最好方式，是列举几个你几乎肯定用过的例子：

• 支付。当结账页面向你的银行卡收费时，它在后台调用支付提供商的 API。商店从不接触你的原始卡片信息；它请求 API 处理交易，然后等待批准或拒绝的响应。
• 地图。一个显示实时地图和预计到达时间的配送应用，是从地图 API 获取地图瓦片、路线和距离，而不是自己构建世界地图。
• 使用 Google 或 Apple 登录。这些按钮使用认证 API，让应用可以确认你的身份，而无需查看你的密码。
• 天气。手机天气应用中的预报来自天气提供商的 API，同样的数据也卖给农业、物流和活动策划公司。
• 社交媒体和流媒体。从第三方应用发帖或获取个性化播放列表，都通过 API 在平台上读写数据。

为什么 API 很重要

API 是现代软件由零部件组装而成而非从头构建的原因。当一个文档齐全的 API 只需几次调用就能完成工作时，没有团队需要自己编写支付处理器、地图引擎或认证系统。这让公司能够更快发货，专注于使其产品与众不同的地方，而不是重建已解决的问题。

它们也创造了真正的商业价值。API 让公司能够接入合作伙伴生态系统，开辟新的分发渠道，并触达原本无法独立服务的客户群体。许多组织现在将其数据和服务本身视为产品：天气公司通过 API 出售预报，银行向金融科技应用公开账户数据，两者都将现有系统转化为收入来源。API 还通过打破数据孤岛来统一客户视图，使应用、网站和聊天机器人能够呈现相同的、一致的最新信息。

当网站没有 API 时：爬取 API

这里存在一个缺口。你可能想要的大量数据存在于根本没有提供官方 API 的公开网站上。信息就在页面上，但没有可调用的干净端点，也没有等待你的 JSON。传统的解决方案是网页抓取：获取页面的 HTML 并自行提取值。这种方法在网站使用 JavaScript 渲染内容、拦截不熟悉的访客、抛出 CAPTCHA 或更改其布局时就会失效，此时一个简单的请求就变成了一个持续的维护问题。

爬取 API 通过将所有这些封装在单一端点后面来弥补这一缺口。你不需要自己管理浏览器、代理和重试，只需发送一个命名你想要的 URL 的请求，然后得到干净的页面响应，这与其他所有 API 使用的请求-响应循环完全一致。实际上，它为没有 API 的网站提供了类似 API 的接口：你像调用天气或支付服务一样调用它，而获取真实页面的混乱部分则保留在契约的另一侧。

一旦页面作为可预测的响应返回，你上面学到的一切都适用了。你可以用库解析 HTML，借助 Python 或 Node.js 请求数据，并将结果传入你自己的应用，就像它来自一个有文档的 JSON 端点一样。该网站就变成了你的代码知道如何调用的又一个 API。

负责任地抓取

像对待 API 一样对待网站，并不能免除你对使用方式的责任。坚守公开数据，阅读并尊重网站的服务条款及其 robots.txt，诚实地标识你的请求，并将请求速率保持在合理范围内，以免给他人的服务器造成压力。托管的爬取 API 通过为你分散和控制请求节奏来帮助你保持礼貌，但关于收集什么内容以及多大力度访问网站的判断仍然由你负责。

常见问题

用简单的话来说，什么是 API？

API 是一套让两个软件程序相互通信的规则。一个程序发送请求以获取数据或执行操作，另一个以约定格式发回响应。就像服务员把你的订单带到厨房并把食物带回来，API 处理对话，这样双方都不需要了解对方内部是如何工作的。

API 和网站有什么区别？

网站是为人设计的：它返回经过浏览器样式化的 HTML，以便人类阅读。API 是为程序设计的：它返回结构化数据（通常是 JSON），其他软件可以直接读取。爬取 API 位于两者之间，获取面向人类的页面，并以可预测的响应交还给你的代码处理。

API 的主要类型有哪些？

最常见的风格是 REST、SOAP、GraphQL 和 webhooks。REST 是灵活、广泛使用的 Web 服务标准。SOAP 是企业和金融领域青睐的更严格、基于 XML 的协议。GraphQL 让客户端从一个端点精确请求所需的字段。Webhooks 颠转了流向，使服务器能够在事件发生时向你的应用推送实时更新。

什么是 JSON，为什么 API 使用它？

JSON（JavaScript Object Notation）是一种将数据表示为键值对和列表的轻量级文本格式。API 青睐它，因为它紧凑、人类易读，并受每种现代编程语言支持，使响应简单易发送、存储和解析。

使用 API 需要 API 密钥吗？

通常需要。许多 API 需要 API 密钥或 Token，以便它们识别你的账户、控制访问并跟踪使用情况。你随每次请求携带密钥，就像在门口出示身份证一样。一些开放 API 允许在没有密钥的情况下有限使用，但大多数生产服务都需要密钥。

如何使用没有 API 的网站？

你可以使用爬取 API，它将网站封装在单一端点之后。你发送一个指定你想要页面的请求，服务为你获取页面，处理渲染、IP 轮换和封锁，然后以干净的响应返回 HTML。从那里你像从任何标准 API 解析数据一样解析数据。

TA

Thomas Adewale

技术撰稿人 · Crawlbase

Crawlbase 技术撰稿人，专注代理网络、轮换策略，以及支撑大规模可靠爬取背后的底层管道。