我用了3年API才发现：那串JSON根本不是API

过去三年，我至少调用了200多次天气接口。直到上周重构一个旧项目时，我突然停下了——

我调用的到底是那个URL，是那串返回的JSON，还是别的什么东西？

这个问题像一根刺。我翻遍了做过的项目：前端用fetch拿数据，后端写Express路由，同事说"这是REST API"，文档里写着"调用API获取响应"。但API本身在哪？是那个函数？那个端点？还是那堆JSON？

我意识到自己对API的理解是一团浆糊。这篇文章记录了我重新梳理的过程，适合同样糊里糊涂用了几年、从没认真想过"接口"到底指什么的开发者。

餐厅服务员模型：API的真正角色

API全称Application Programming Interface（应用程序编程接口）。这个名字听起来像考试重点，但核心就一句话：API是一套规则，让两个软件能按约定的方式对话。

用餐厅打个比方。你坐在餐桌前，不会冲进厨房自己炒菜。你告诉服务员要什么，服务员把需求转达给厨房，再把做好的菜端回来。API就是那个服务员——它不生产数据，也不消费数据，它只负责按规则传递请求和响应。

这个类比帮我理清了一个关键混淆点。以前我写这样的代码：

fetch("https://api.example.com/weather?city=Kolkata")

.then(res => res.json())

.then(data => console.log(data));

拿到返回的JSON时，我心里默认"这就是API"。但JSON只是API的响应内容，不是API本身。就像服务员端来的菜不是服务员，API是传递JSON的那套机制——URL格式、请求方法、参数规则、响应结构，这些加在一起才是API。

前端调用的、后端写的，是同一个东西吗

另一个困惑来自前后端语境的切换。前端同事说"调API"，后端同事说"写API"，听起来像两个动作，但指向同一个名词。

实际上确实是同一个东西，只是视角不同。前端调用天气服务时，API是外部系统暴露的访问点；后端写这样的代码时，API是自己系统对外暴露的能力边界：

app.get("/users", (req, res) => {

res.json([

{ id: 1, name: "Pratik" },

{ id: 2, name: "Aman" }

这个Express路由允许客户端请求用户数据。当前端向/users发请求，后端返回响应——这条路由就成了API的一个端点（endpoint）。所以"写API"就是定义这些规则和端点的过程。

我现在记住的定义是：API是一套规则和端点的集合，让一个软件系统能与另一个通信。在Web开发里，通常表现为客户端发请求、服务端返响应的模式。

"类型"这个词为什么总让人晕

搜索API类型时，结果很混乱。有人说公有API、私有API，有人说REST、GraphQL、RPC——前者是按使用者权限分类，后者是按技术实现分类，混在一起讲自然糊涂。

公有API（Public API）对外开放，比如天气服务给所有开发者用。你写天气App需要实时温度，直接fetch他们的接口，这就是消费公有API。私有API（Private API）仅限内部系统调用，比如你的用户服务只给订单服务用，外部拿不到。

实现方式上，REST是目前最常见的，用HTTP方法（GET/POST/PUT/DELETE）表达操作，返回JSON。但REST不是唯一选择，GraphQL让你一次请求精确拿到想要的数据结构，RPC（远程过程调用）更像在本地调函数一样调远端服务。

这些分类维度不同，但核心没变：都是按约定格式交换数据的机制。选哪种取决于你的场景——需要灵活查询选GraphQL，追求简单普及选REST，内部高性能服务可能用gRPC。

那个让我愣住的具体场景

回到我卡住的那个重构项目。代码里有一行：

const api = await fetch('/api/v2/orders');

变量名就叫api。但fetch返回的是Response对象，解析后才是数据。那我写的api到底是API，还是API的响应？

命名暴露了我的认知混乱。实际上，'/api/v2/orders'这个端点加上它背后的规则才是API，fetch是调用动作，Response是结果。我把三个层次的东西用一个变量名混过去了，写的时候没感觉，三年后读起来像谜语。

现在我会在团队里刻意区分："这个API的响应格式变了"而不是"这个API变了"，"新增一个API端点"而不是"写一个API"。用词精确一点，沟通成本降很多。

有个细节让我印象很深。上周问组里一个五年经验的后端同事："你说'暴露一个API'，具体暴露的是什么？"他愣了一下，说"就是开个接口让别人调啊"。我再问"接口是指URL、函数、还是文档"，他想了想说"都有吧，主要是约定"。

这个回答其实挺准确——API最终是一种约定。URL、函数、文档都是约定的载体，但约定本身才是核心。两个系统能对话，不是因为它们物理上连上了，而是因为它们对"怎么请求、怎么响应、出错怎么办"有共同理解。

你现在回头看自己项目里的API调用，能分清哪些是规则、哪些是响应、哪些只是命名习惯吗？