API 是什么？软件之间是怎么“互相办事”的？

打开天气 App，你想知道今天有多少度。App 可以向天气服务取得数据，再把它画成你看得懂的温度和图标。让程序按约定调用另一方能力的这套接口，就叫 API。你点的是屏幕上的按钮，程序用的是 API。

一次查询怎么完成

API 的全称是 Application Programming Interface，中文通常叫“应用程序编程接口”。

假设我们要做一个简单的天气页面，数据使用 Open-Meteo 提供的天气 API。它的官方文档约定：查询时需要给出地点的经纬度，还可以指定想取得的天气变量。比如，temperature_2m 表示距地面两米处的气温，放进 current 参数，表示要取得当前天气条件中的这一项。

一次查询可以这样走：

1. 页面发出请求。 它向约定的服务地址说明地点，以及“我要这一地点的当前气温”。这里的请求，就是程序按规定提出的一次调用；地点和天气项目叫参数。
2. 天气服务处理请求。 它根据这些参数提供相应的天气数据。数据来自服务方的天气模型，页面不需要自己运行整套天气模型。
3. 服务返回结果。 结果中可以有时间、气温数值和单位等字段，页面按约定找到需要的内容。
4. 页面把结果画出来。 假如结果中的温度是 24，单位是摄氏度，页面就可以显示“24°C”。这个数字只是说明显示过程的示意值，不是实时天气或实测记录。

你看到的太阳图标、字体和颜色，属于页面的显示设计。API 返回的数据与最终看到的界面，是这个过程中的两件事。

Open-Meteo 用 JSON 返回这类结果。JSON 是一种组织数据的文本格式，让程序能区分哪个字段是时间、哪个是温度。其他 API 也可以使用别的格式；“API”和“JSON”不是同一个概念。Open-Meteo 官方文档[1]说明了这里用到的参数、结果格式，以及当前天气条件来自天气模型这一边界。

API 与接口的关系

“接口”是个范围更宽的词。你点击的软件按钮和菜单属于用户界面，开发者写代码调用的程序接口则是 API。说到硬件时，USB-C 这样的连接口也会被叫作接口。

API 本来就是一种接口；在开发者聊天的语境里，“这个接口返回了什么”中的“接口”，往往直接指某个 API。

理解这里的关系，可以分别看：人怎样使用这个软件，程序又怎样使用它提供的能力。 MDN 的 API 定义[2]将它描述为供软件交互的一组能力和规则。

为什么要约定规则

回到天气页面。它需要的是某个地点的天气结果，并不需要知道天气服务内部怎样整理模型数据、用了哪些存储系统。

API 给双方划出了一条合作边界：提供方说明能做哪些事、调用时要给什么信息、结果怎样表达；调用方按这个约定使用能力。至于服务内部怎么实现，可以由提供方自己安排。内部改动后，仍要维持对外约定，已有调用才能继续工作。

这也能解释“接入 API”这句话：开发者把自己的程序写成能按对方规则调用的样子，让已有能力进入自己的软件。天气页面可以调用天气服务，其他程序也可以借助各自的 API 查询资料、处理文件或控制某种功能。

API 不会自动替开发者完成这些连接。参数怎么组织，取得结果以后做什么，失败时怎样提醒用户，都需要调用方写好相应的处理。

所有 API 都要联网吗

天气例子用到了网络，但 API 的范围比网络服务大。

浏览器就内置了许多 API。例如，网页程序可以通过 Web Audio API 调整音频的音量或添加效果，具体音频处理由浏览器完成。调用这种能力本身，不要求把音频送到一个远端服务器；音频素材从哪里取得，是另一件事。MDN 的 Web API 入门[3]介绍了这类浏览器内置能力。

因此，API 可以连接网络上的服务，也可以让程序使用本机软件或组件的能力。它不一定是一条网址，也不一定对应另一个独立运行的 App。

有接口也要有权限

提供一个 API，并不意味着所有人都能随意使用它的全部功能。

有些公开数据接口允许匿名查询；有些调用需要带上 API key 或访问令牌，供服务确认调用身份及权限。API key 和令牌是常见的凭据形式，具体作用由服务设计决定，不能把它们一概当成“拿到就拥有全部权限”。例如，GitHub REST API 文档[4]要求认证令牌具备相应的权限或范围。

调用也可能失败。参数写错，服务可能返回错误说明；权限不够，请求可能被拒绝；网络中断，则可能根本收不到结果。Open-Meteo 的文档就列出了参数不正确时的错误响应。

下次看到“支持 API”，可以先看它开放了什么能力、需要提供什么信息、怎样返回结果，以及谁有权调用。这些约定说明了两个软件准备怎样合作。

参考资料

• [1] Open-Meteo 官方文档：https://open-meteo.com/en/docs
• [2] MDN 的 API 定义：https://developer.mozilla.org/en-US/docs/Glossary/API
• [3] MDN 的 Web API 入门：https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Client-side_APIs/Introduction
• [4] GitHub REST API 文档：https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api