互联网的桥梁：认识API

互联网的桥梁：认识API

当你滑动屏幕时，发生了什么？

你打开手机，点开那个你最喜欢的短视频应用，手指轻轻向上一滑，一条有趣的视频立刻出现在屏幕上。你看完后点了赞，又评论了一句“哈哈哈太有意思了”。这一切发生得如此自然，以至于你几乎不会去思考：在你手指滑动的那一瞬间，在你看不到的地方，无数复杂的系统正在有条不紊地协同工作，只为了给你展示那短短几十秒的快乐。

但如果我们稍微暂停一下，问一个看似简单的问题：你的手机是怎么知道该给你展示哪条视频的？它从哪里获取的视频数据？当你点击点赞按钮时，这个“点赞”的动作是如何被记录下来的？

答案就藏在本书要讨论的核心概念中——API。

API，全称Application Programming Interface，中文译作“应用程序编程接口”。这个名字听起来可能有些拗口和抽象，但请放心，在接下来的内容中，我们会用大量的生活案例和实际演示，让你对API有一个清晰、直观、深刻的理解。你会发现，API其实就在你每天的日常使用中，而你早就已经是一个“API用户”了——只是以前没有人告诉你而已。

让我们从你最熟悉的一个场景开始。

餐厅里的秘密：理解API的第一把钥匙

想象这样一个场景：你走进一家餐厅，坐下来准备点餐。这家餐厅有点特别——厨房是封闭的，你看不到里面发生了什么，你也无法直接进入厨房自己动手。那么问题来了：你怎样才能吃到你想吃的东西？

答案很简单：你需要通过服务员来传达你的需求。

你翻开菜单，看到上面写着“红烧肉套餐”、“清炒时蔬”、“宫保鸡丁”……你决定要点一份红烧肉套餐和一碗米饭。你招手叫来服务员，告诉他你的选择。服务员走到厨房，把你的订单交给厨师。厨师按照你的要求开始烹饪，完成后把做好的菜交给服务员。服务员再把你的红烧肉套餐和米饭端到你的桌上。

整个过程，你没有进入厨房，没有和厨师直接交流，甚至不知道厨房里有多少人在工作、用了什么样的锅具和炉灶。但你成功地获得了你想要的食物。

这个场景，几乎完美地类比了API的工作方式。

在API的世界里，你的手机应用（或网页）就像坐在餐厅里的顾客，而提供数据的服务器就像那间封闭的厨房。顾客不需要知道厨房里的复杂情况，只需要告诉服务员（API）“我想要什么”，然后就能得到结果。服务员就是这个中间层，负责接收需求、传达指令、返回结果。

让我们把这个类比再细化一点：

菜单就像是API提供的接口文档，它告诉你这家餐厅（服务器）能提供什么服务。你可以在菜单上看到“红烧肉套餐”、“清炒时蔬”等选项，API文档则会告诉你能获取哪些数据、能调用哪些功能。

点菜的动作就像是你调用API。你对服务员说“我要一份红烧肉套餐”，这相当于你在代码中写下一行API调用请求。

服务员传递订单并取回菜品的这个过程，就像是API的请求-响应机制。你的请求被发送出去，服务器处理你的请求，然后把结果返回给你。

端到你桌上的红烧肉套餐就是API的响应——你真正想要得到的东西。

现在，让我们把这个类比再往技术方向推进一步。

服务员小李的工牌：理解API的地址和格式

在你经常光顾的餐厅里，服务员小李有一张工牌，上面写着他的工号和他的职责范围。比如，工牌上可能会写：“工号A-07，负责一楼大厅区域，可接受点餐、加菜、买单请求”。这样，你就知道该找谁、什么时候找他、找他可以做什么。

API也有类似的“工牌”，只不过它不是一张纸，而是一个URL（Uniform Resource Locator，统一资源定位符），也就是我们在浏览器地址栏里看到的那种网址。

例如，当你想获取某个用户的信息时，API可能会给你一个这样的地址：

``` https://api.example.com/users/12345 ```

这个地址告诉我们几个重要信息：

1. 去哪里找这个服务：`api.example.com`是服务器的网络地址，类似于餐厅的地址。你需要知道去哪里才能得到服务。

2. 要找什么：`/users`表示你想要获取的是“用户”相关的数据。

3. 要找谁：`/12345`表示你想要的具体的用户ID是12345。

这就像是你告诉服务员：“我要找工号A-07的那位服务员”，然后服务员就知道自己该去找谁了。

但光有地址还不够。你还需要知道该怎么“说话”。如果你用中文点餐，但厨师只会说英语，你可能需要一位翻译，或者至少需要用双方都能理解的方式交流。API也是一样，它需要一种双方都能理解的“语言”来沟通，这就是所谓的协议。

最常见的协议是HTTP（HyperText Transfer Protocol，超文本传输协议）。当你打开一个网页时，你的浏览器就是通过HTTP协议和服务器“说话”的。API通常也使用HTTP协议进行通信。

在HTTP的世界里，常见的有几种“说话方式”，我们称之为请求方法（Request Method）：

• **GET**：获取资源，就像你问服务员“给我看看菜单”
• **POST**：提交新数据，就像你点了一道新菜
• **PUT**：更新现有数据，就像你把之前点的菜换成另一道
• **DELETE**：删除数据，就像你取消了还没做的菜

每一种方法都有它特定的用途，API通过这些方法来理解你想要做什么。

你的手机在“打电话”：客户端与服务器

让我们回到手机刷视频的场景。当你打开短视频应用并上滑刷新时，你的手机应用（客户端）正在和远程的服务器“打电话”。

这里出现了两个关键概念：

客户端（Client） 是指主动发起请求的一方。在日常生活中，你的手机应用、浏览器、甚至智能音箱都可以是客户端。它们负责收集你的操作（比如滑动屏幕、点击按钮），然后把这些操作转换成请求，发送给服务器。

服务器（Server） 是指接收请求并进行处理的一方。它通常是一台或者一群性能强大的计算机，存放着大量的数据和程序。当它收到客户端的请求时，会根据请求的内容执行相应的操作，然后把结果返回给客户端。

这个过程就像是你打电话给餐厅订餐。你（客户端）拿起电话拨出号码，餐厅的总机（服务器）接听你的电话，接收你的订单，然后让厨房准备食物，最后再通过电话告诉你订单已经收到、什么时候可以取餐。

在真实的互联网环境中，这个过程可能比你想象的复杂得多。

想象一下，当你打开抖音刷视频时，背后可能涉及数十个不同的服务：

• 一个服务负责验证你的身份（确保你是真正的用户）
• 一个服务负责记录你的点赞和评论
• 一个服务负责推荐可能感兴趣的视频
• 一个服务负责存储和传输视频文件本身
• 一个服务负责显示广告（毕竟服务器也要赚钱）

这些服务之间又相互调用，形成了一个复杂的网络。但对于你——普通的用户来说——这一切都被隐藏在友好的界面背后。你只需要滑动屏幕、点赞评论，其他的事情，API会帮你搞定。

这就是API的另一个重要作用：抽象复杂性和封装细节。

作为开发者，你不需要知道抖音的推荐算法是怎么工作的，不需要知道视频是怎么存储和传输的，你只需要调用相应的API，告诉它“我想获取推荐视频列表”或者“我想给这个视频点赞”，它就会帮你完成这些操作，并返回你想要的结果。

API的家族史：从RPC到REST的故事

任何技术的发展都有其历史脉络，API也不例外。理解API的演变过程，不仅能帮助我们理解现在流行的技术为什么是这样设计的，还能让我们在未来的技术变革中更好地把握方向。

让我们把时间拨回到计算机发展的早期阶段。

远程过程调用：最早的API雏形

在上世纪七八十年代，计算机还是体积庞大、价格昂贵的庞然大物，通常只有大型机构才能拥有。为了让多台计算机能够协同工作、共享资源，研究人员开始探索让一台计算机能够“调用”另一台计算机上的程序的方法。这就是RPC（Remote Procedure Call，远程过程调用） 的诞生背景。

RPC的核心思想很简单：像调用本地函数一样调用远程函数。

假设你有一台电脑，上面有一个计算两个数相加的函数：

```python def add(a, b): return a + b ```

如果另一台电脑想要使用这个函数，在传统的编程方式下，它需要自己写一个相同的函数。但如果使用RPC，事情就变得简单了——它可以直接“调用”远程电脑上的这个函数，就像它就在本地一样。

```python

调用远程的add函数

result = remote_computer.add(3, 5) print(result) # 输出8 ```

这在当时是一项革命性的技术，它让分布式计算变得可行。但RPC也有它的局限性：它通常依赖于特定的平台和编程语言，不同系统之间的通信往往存在障碍。

Web API的崛起：REST的统治时代

随着互联网的蓬勃发展，人们越来越需要在不同的网站和服务之间共享数据。这时候，一个更加标准化、更加轻量的方案出现了——REST（Representational State Transfer，表现层状态转移）。

REST不是一种编程语言或技术，而是一种架构风格。它由Roy Fielding在他的博士论文中提出，并在2000年代初期开始被广泛采用。

那么，REST有什么特点呢？让我们用最简单的话来概括：REST是一种让客户端和服务器以“资源”为中心进行交互的设计风格。

在REST的世界里，一切都是“资源”——一个用户、一篇文章、一张图片、一段视频都是资源。每个资源都有一个唯一的标识符（URI），就像每本书都有一个ISBN号一样。

当你想要获取某个资源时，你会发送一个GET请求：

```http GET https://api.example.com/articles/100 ```

当你想要创建一个新资源时，你会发送一个POST请求：

```http POST https://api.example.com/articles Content-Type: application/json

{ "title": "我的第一篇文章", "content": "这是文章的内容..." } ```

REST的设计哲学强调以下几点：

1. 无状态性：每个请求都应该包含服务器理解该请求所需的所有信息，服务器不需要“记住”之前的请求内容。

2. 统一的接口：所有的交互都通过标准化的HTTP方法进行，这使得REST API具有很高的可预测性。

3. 可缓存性：服务器可以标记某些响应为可缓存的，这有助于提高性能。

正是因为这些特点，REST在过去的二十多年里一直是Web API领域的主导者。你现在访问的大多数网站的API，都是RESTful API。

后REST时代：GraphQL与gRPC的崛起

然而，随着应用场景变得越来越复杂，REST的一些局限性也开始显现出来。

最大的问题之一是过度获取（Over-fetching）和获取不足（Under-fetching）。

想象一下，你想在一个社交媒体应用中显示用户的基本信息（用户名和头像）。如果这个应用使用的是REST API，它可能会提供一个这样的端点：

```http GET /users/123 ```

返回的数据可能包含用户的所有信息：

```json { "id": 123, "username": "小明", "avatar": "https://example.com/avatars/xiaoming.jpg", "email": "xiaoming@example.com", "phone": "13800138000", "birthday": "2005-06-15", "address": "北京市朝阳区...", "bio": "...", "followers_count": 1234, "following_count": 567, "posts_count": 89, "created_at": "2020-01-01", "last_login": "2024-01-15" } ```

但你只是想显示用户名和头像！这些额外的数据不仅浪费了网络带宽，还需要客户端进行额外的数据处理。

为了解决这个问题，Facebook在2015年推出了GraphQL。

GraphQL的核心思想是：让客户端精确地指定它需要什么数据，而不是服务器返回什么数据。

使用GraphQL，你可以这样请求：

```graphql query { user(id: 123) { username avatar } } ```

服务器只会返回你请求的字段：

```json { "data": { "user": { "username": "小明", "avatar": "https://example.com/avatars/xiaoming.jpg" } } } ```

GraphQL解决了数据获取灵活性的问题，但它也有自己的适用场景。对于复杂的查询和灵活的数据需求，GraphQL是很好的选择；但对于简单的CRUD（增删改查）操作，REST仍然是一个简洁有效的方案。

与此同时，在另一个赛道上，gRPC正在获得越来越多的关注。

gRPC最初由Google开发，它使用了一种与REST完全不同的技术方案：使用Protocol Buffers作为接口定义语言和数据序列化格式，使用HTTP/2作为传输协议。

与JSON相比，Protocol Buffers的二进制格式更加紧凑，解析速度也更快。这使得gRPC在性能和带宽效率上有显著优势，特别适合微服务之间的通信。

gRPC还有一个独特的特性——双向流。在传统的HTTP请求中，客户端发送请求，服务器返回响应，然后连接就关闭了。但在gRPC中，客户端和服务器都可以在同一个连接上连续发送多个消息，这为实时性应用（如视频通话、实时游戏）提供了更好的支持。

下表总结了这几种API设计风格的主要区别：

| 特性 | REST | GraphQL | gRPC | |------|------|---------|------| | 数据格式 | JSON | JSON | Protocol Buffers（二进制） | | 传输协议 | HTTP/1.1 | HTTP/1.1或HTTP/2 | HTTP/2 | | 请求方式 | 请求-响应 | 请求-响应 | 支持双向流 | | 学习曲线 | 低 | 中 | 高 | | 适用场景 | 通用Web API | 复杂数据查询 | 高性能微服务通信 |

理解这些不同的API风格，有助于你在未来的学习和工作中选择合适的工具。在本书的后续章节中，我们会分别深入讲解REST、GraphQL和gRPC，带你掌握这三种最重要的API设计技术。

一次完整的API调用：端到端的旅程

理论讲得再多，不如实际动手。让我们亲身体验一次API调用的完整流程。

为了演示方便，我们将使用一个真实存在且完全免费的API服务——JSONPlaceholder。这是一个专门用于测试和学习API的“假”API服务，它会返回模拟数据，帮助开发者练习API调用。

准备工作：什么是API测试工具

在开始之前，我们需要一个工具来发送API请求。就像你要打电话需要一部手机一样，发送HTTP请求也需要工具。

对于初学者，我推荐使用几种常用的工具：

浏览器开发者工具：如果你用的是Chrome浏览器，按F12打开开发者工具，切换到"Network"（网络）标签，然后刷新网页。你就能看到浏览器发送的所有请求和收到的响应。

Postman：这是一个专门为API开发者设计的工具，界面友好，功能强大。它允许你构建、测试和分享API请求。你可以从官网下载Postman，创建免费账户后就能使用。

curl：对于喜欢命令行的人来说，curl是一个经典的选择。它是一个在终端中发送HTTP请求的工具，语法简洁但功能强大。

让我们先用Postman来体验一下。打开Postman，你会看到一个简洁的界面：

• 顶部有一个下拉菜单，用来选择请求方法（GET、POST等）
• 旁边有一个输入框，用来输入URL
• 下方有多个标签页，包括"Params"（参数）、"Headers"（请求头）、"Body"（请求体）等

第一次GET请求：获取文章列表

让我们从最简单的开始——获取文章列表。

在URL输入框中输入：

``` https://jsonplaceholder.typicode.com/posts ```

确保请求方法选择的是"GET"，然后点击"Send"按钮。

几秒钟后，你会看到响应区域显示出类似这样的内容：

```json [ { "userId": 1, "id": 1, "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit", "body": "quia et suscipit\nsuscipit recusandae consequuntur ..." }, { "userId": 1, "id": 2, "title": "qui est esse", "body": "est rerum tempore vitae\nsequi sint nihil MDCreprehenderit ..." }, // ... 更多文章 ] ```

恭喜你！你刚刚完成了第一次API调用！

这个响应是一个JSON格式的数组，每一项代表一篇文章。文章包含以下字段：

• `userId`：作者的用户ID
• `id`：文章的唯一标识符
• `title`：文章的标题
• `body`：文章的正文内容

从响应中我们可以看到，API返回了100篇文章（虽然这里只显示了前两篇的片段）。这些数据来自远程服务器，经过网络传输，最终呈现在你的面前。

添加URL参数：筛选特定数据

如果我只想要ID为5的文章怎么办？我们可以使用URL参数来筛选。

在URL后面加上`?id=5`：

``` https://jsonplaceholder.typicode.com/posts?id=5 ```

这次，响应只会返回ID为5的那一篇文章：

```json [ { "userId": 1, "id": 5, "title": "nesciunt quas odio", "body": "repudian