什么是API

本文属于《从 0 到 1 AI 产品出海知识库》中的「技术栈入门与项目架构」章节。

如果你曾经用过地图导航、在线支付、或者调用 AI 模型生成文本，你就已经在「使用 API」了。API 是前后端沟通的桥梁，也是现代软件系统中最重要的协作机制之一。本文从零开始，帮你建立对 API 的完整认知。

1. API 是什么

API 的全称是 Application Programming Interface，中文叫「应用程序编程接口」。简单来说，API 就是两个程序之间约定好的一套沟通规则——一方按规则发请求，另一方按规则给响应。

用一个生活类比来理解：你去餐厅吃饭，你（前端）不需要知道厨房（后端）怎么做菜，你只需要通过菜单（API 接口定义）点菜，服务员（API 运行时）会把你的需求传给厨房，再把做好的菜端回来。整个过程中，你和厨房各自独立工作，通过菜单和服务员完成协作。

在软件开发中，API 是前后端的「契约」：

前端负责界面展示和用户交互
后端负责数据存储和业务逻辑
API 定义了前端可以向后端请求什么数据、发送什么数据，以及数据格式是什么

这个契约通常以 URL、HTTP 方法、请求参数和响应格式来描述。只要双方遵守契约，前端和后端可以独立开发、独立部署、独立迭代。

2. REST API 的核心概念

在众多 API 设计风格中，REST（Representational State Transfer，表述性状态转移）是目前最主流的一种。遵循 REST 约束构建的 API 叫做 REST API 或 RESTful API。

2.1 资源（Resource）

REST 的核心思想是：一切皆资源。用户是一条资源，订单是一条资源，一篇博客也是一条资源。每个资源通过一个唯一的 URL 来标识：

https://api.example.com/users/42       # ID 为 42 的用户
https://api.example.com/orders/10086   # ID 为 10086 的订单

URL 就是资源的「地址」，就像每栋房子都有自己的门牌号一样。

2.2 HTTP 方法

REST 用 HTTP 协议的标准方法来表达对资源的操作。不同的方法对应不同的语义：

HTTP 方法	操作语义	CRUD 对应	幂等性	说明
`GET`	读取资源	Read（查）	幂等	多次请求结果相同，不修改服务器数据
`POST`	创建资源	Create（增）	非幂等	每次请求可能创建新资源
`PUT`	全量更新资源	Update（改）	幂等	用请求体的完整数据替换目标资源
`PATCH`	部分更新资源	Update（改）	非幂等	只修改资源的部分字段
`DELETE`	删除资源	Delete（删）	幂等	多次请求结果相同，资源被删除

幂等是什么意思？同一个请求发送一次和发送多次，服务器端的状态变化是一样的。GET、PUT、DELETE 是幂等的，POST 不是。

举个例子，假设我们要管理一个用户列表：

GET    /api/users          → 获取所有用户
GET    /api/users/42       → 获取 ID 为 42 的用户
POST   /api/users          → 创建一个新用户
PUT    /api/users/42       → 完整更新用户 42 的信息
PATCH  /api/users/42       → 部分更新用户 42 的某个字段
DELETE /api/users/42       → 删除用户 42

2.3 状态码（Status Code）

服务器处理完请求后，会返回一个 HTTP 状态码，告诉客户端结果如何。状态码分为五大类：

状态码范围	类别	含义	常见示例
`1xx`	信息性	请求已接收，继续处理	`100` Continue
`2xx`	成功	请求成功处理	`200` OK、`201` Created、`204` No Content
`3xx`	重定向	需要进一步操作才能完成	`301` 永久重定向、`302` 临时重定向
`4xx`	客户端错误	请求有误，服务器无法处理	`400` Bad Request、`401` Unauthorized、`403` Forbidden、`404` Not Found
`5xx`	服务器错误	服务器处理请求时出错	`500` Internal Server Error、`502` Bad Gateway、`503` Service Unavailable

日常开发中最常遇到的是 200（成功）、201（已创建）、400（请求参数错误）、401（未认证）、403（无权限）、404（资源不存在）和 500（服务器内部错误）。

3. 请求和响应的格式

一次 API 调用由「请求」和「响应」两部分组成。理解它们的结构，是调用任何 API 的基础。

3.1 请求（Request）

一个 HTTP 请求包含以下要素：

请求行：HTTP 方法 + URL + HTTP 版本
请求头（Headers）：附加信息，如认证凭据、内容类型、客户端信息等
请求体（Body）：发送给服务器的数据（GET 请求通常没有请求体）

以创建一个新用户为例：

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
 
{
  "name": "张三",
  "email": "[email protected]",
  "role": "editor"
}

这里有两个重要的请求头：

Content-Type: application/json — 告诉服务器「我发的是 JSON 格式的数据」
Authorization: Bearer ... — 携带认证令牌，证明「我是谁」

3.2 响应（Response）

服务器处理完请求后返回响应，包含：

状态行：HTTP 版本 + 状态码 + 状态描述
响应头：服务器信息、内容类型、缓存策略等
响应体：返回给客户端的数据

一个典型的响应如下：

HTTP/1.1 201 Created
Content-Type: application/json
 
{
  "id": 43,
  "name": "张三",
  "email": "[email protected]",
  "role": "editor",
  "createdAt": "2026-07-01T10:30:00Z"
}

3.3 JSON 格式

JSON（JavaScript Object Notation）是目前 API 通信中最常用的数据格式。它使用键值对的结构，人类可读，机器也好解析：

{
  "id": 42,
  "name": "李四",
  "tags": ["designer", "frontend"],
  "active": true,
  "address": null
}

JSON 支持的数据类型包括：字符串、数字、布尔值、数组、对象和 null。几乎所有编程语言都有 JSON 的解析库。

在 REST API 的早期，XML 是主流的数据格式。如今 JSON 已经基本取代了 XML 在 API 领域的地位，因为 JSON 更轻量、更易读、与 JavaScript 天然兼容。

4. API 认证方式

API 认证要解决的核心问题是：服务器如何确认「这个请求确实是合法的客户端发出的」？以下是几种最常见的认证方式。

4.1 API Key

API Key 是最简单的认证方式。服务方给你分配一个唯一的密钥字符串，你在每次请求中携带它。通常放在请求头或 URL 参数中：

GET /api/data?api_key=sk_abc123def456 HTTP/1.1

API Key 适合服务端到服务端的简单集成，比如调用第三方数据接口。它的缺点是安全性较低——如果 Key 泄露，任何人都能冒充你发起请求。

4.2 JWT（JSON Web Token）

JWT 是一种基于令牌的认证机制。用户登录成功后，服务器签发一个 JWT，里面包含用户信息和过期时间，并用密钥签名。客户端在后续请求中携带这个令牌：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjQyLCJyb2xlIjoiYWRtaW4iLCJpYXQiOjE3MTk4MDAwMDB9.xxx

JWT 的结构分三段：Header（头部）、Payload（载荷）、Signature（签名），用 . 连接。服务器不需要查数据库就能验证令牌的有效性，这种「无状态」的特性让 JWT 非常适合分布式系统。

4.3 OAuth 2.0

OAuth 2.0 是一种授权框架，用于让第三方应用在用户授权的前提下访问其资源，而不需要把密码交给第三方。你用微信登录某个 App、用 Google 账号授权某个网站，背后都是 OAuth 在运作。

OAuth 2.0 的核心流程包含四个角色：资源所有者（用户）、客户端（第三方应用）、授权服务器、资源服务器。常见的授权模式有授权码模式（Authorization Code）、客户端凭证模式（Client Credentials）等。

4.4 认证方式对比

认证方式	安全等级	复杂度	适用场景	是否有状态
API Key	低	简单	服务端间简单集成、内部测试	有状态（需查库验证）
Basic Auth	低	简单	内部 API、开发调试	每次携带凭据
JWT	中高	中等	用户认证、前后端分离应用	无状态（令牌自包含）
OAuth 2.0	高	复杂	第三方授权、社交登录	视具体模式而定

选择认证方式时需要权衡：内部测试用 API Key 就够了；前后端分离的用户系统用 JWT 是主流方案；需要接入第三方平台（微信、Google 等）则必须用 OAuth 2.0。

5. 常见 API 使用场景

API 在现代软件开发中无处不在。以下是几个最常见的场景。

5.1 前后端通信

这是 API 最基础的用途。前端页面需要展示用户列表、提交表单、搜索内容，都通过 API 与后端交互。比如用户注册页面调用 POST /api/users 提交注册信息，个人中心调用 GET /api/users/me 获取用户资料。

5.2 第三方服务集成

几乎所有主流 SaaS 产品都提供 API。你的应用可以通过 API 集成短信发送（Twilio）、邮件营销（SendGrid）、文件存储（AWS S3）、地图服务（Google Maps）等能力，而不需要自己从零搭建。

5.3 AI 服务调用

AI 产品出海的核心能力之一就是调用大模型 API。OpenAI、Anthropic、Google 等都提供标准的 REST API 接口。你发送 Prompt 文本，API 返回模型生成的内容。整个过程和调用普通 API 没有区别，只是请求和响应的字段有所不同。

5.4 支付集成

在线支付是出海产品的基础设施。Stripe、PayPal 等平台通过 API 完成支付流程：创建订单、发起扣款、处理退款、接收 Webhook 回调通知。理解 API 是接入任何支付系统的前提。

5.5 微服务间通信

在微服务架构中，一个业务功能可能被拆分成多个独立服务。这些服务之间也通过 API 进行通信。比如订单服务需要调用用户服务获取用户信息、调用库存服务检查库存——每次调用都是一次 API 请求。

6. REST vs GraphQL

除了 REST，GraphQL 是另一种近年来流行的 API 查询语言。两者各有特点：

对比维度	REST API	GraphQL
数据获取	每个端点返回固定结构的数据	客户端自定义查询字段，一次请求获取所需数据
端点数量	多个端点（`/users`、`/orders`...）	单一端点（通常只有一个 `/graphql`）
过度获取	可能返回不需要的字段（Over-fetching）	精确获取客户端需要的字段
欠获取	可能需要多次请求才能获取完整数据（Under-fetching）	一次请求获取所有关联数据
缓存	HTTP 原生缓存机制	需要额外方案（如 Apollo Cache）
学习成本	低，基于 HTTP 标准	较高，需要学习 Schema 定义和查询语法
典型用户	GitHub API、Stripe API、Twilio API	GitHub GraphQL API、Shopify Storefront API

对于大多数团队来说，REST 仍然是更稳妥的选择——生态成熟、工具丰富、新人上手快。GraphQL 适合数据关系复杂、前端需要灵活查询的场景。两者不是替代关系，很多项目同时使用 REST 和 GraphQL。

7. 案例：调用 OpenAI API

OpenAI 的 Chat Completions API 是 AI 产品出海最常用的接口之一。以下是一个实际的调用示例。

请求：

curl https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "你是一个 helpful assistant."},
      {"role": "user", "content": "什么是API？请用一句话解释。"}
    ],
    "temperature": 0.7
  }'

响应：

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gpt-4o-mini-2024-07-18",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "API 是两个软件程序之间约定好的沟通接口，一个程序按规则发送请求，另一个程序按规则返回数据。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 45,
    "total_tokens": 73
  }
}

这个例子展示了 API 调用的完整流程：指定 URL、设置请求头（内容类型和认证信息）、构造 JSON 格式的请求体、发送请求、解析 JSON 格式的响应。

几个关键点：

认证方式使用 Bearer Token，sk- 开头的是 API Key
model 字段指定要使用的模型
messages 数组包含对话历史，system 角色设定 AI 的行为规则
usage 字段告诉你消耗了多少 Token，这关系到计费

8. 案例：Stripe 支付 API

Stripe 是出海产品最主流的支付集成方案。以下是通过 Stripe API 创建一个支付意图的示例：

请求：

curl https://api.stripe.com/v1/payment_intents \
  -u sk_test_your_secret_key: \
  -d amount=2000 \
  -d currency=usd \
  -d "payment_method_types[0]=card" \
  -d "metadata[order_id]=6735"

响应：

{
  "id": "pi_3MtwBwLkdIwHu7ix28a3tqPa",
  "object": "payment_intent",
  "amount": 2000,
  "currency": "usd",
  "status": "requires_payment_method",
  "client_secret": "pi_3MtwBwLkdIwHu7ix28a3tqPa_secret_O6Az2SpKn",
  "metadata": {
    "order_id": "6735"
  }
}

几个值得注意的地方：

Stripe 使用 HTTP Basic Auth，-u sk_test_xxx: 的方式传递密钥
金额单位是「分」而不是「元」，2000 表示 20.00 美元
client_secret 需要传给前端，用于 Stripe.js 完成支付确认
status 字段表示当前支付状态，requires_payment_method 表示等待用户提供支付方式

从这两个案例可以看出，不同 API 的认证方式、请求格式和响应结构各有差异，但底层的 HTTP 请求/响应模型是一致的。掌握了 REST API 的基础知识，就能快速上手任何第三方 API。

9. API 请求响应流程

用一张流程图来理解一次完整的 API 调用过程：

流程图画布 · 115%

Mermaid 流程图加载中...

这个流程展示了从客户端发起请求到最终拿到响应的完整链路。在实际的生产环境中，API 网关层还会处理鉴权、限流、日志记录、负载均衡等横切关注点。

10. API 开发检查清单

无论是调用第三方 API 还是自己开发 API，以下检查清单可以帮助你避免常见陷阱：

所有 API 通信是否强制使用 HTTPS？
URL 路径是否使用名词（/users）而非动词（/getUsers）？
HTTP 方法是否正确使用了语义（GET 读取、POST 创建、PUT 更新、DELETE 删除）？
是否返回了合适的 HTTP 状态码？
请求和响应的数据格式是否统一使用 JSON？
是否实现了合适的认证机制（API Key / JWT / OAuth）？
敏感信息（密码、密钥）是否从响应中移除？
是否实现了请求频率限制（Rate Limiting）？
是否提供了清晰的错误信息（包含错误码和错误描述）？
是否有 API 版本管理策略（如 /v1/ 前缀或 Accept 请求头）？
是否编写了 API 文档（如 OpenAPI/Swagger 规范）？
是否考虑了 CORS（跨域资源共享）配置？
对于分页接口，是否实现了合理的分页方案（offset 或 cursor）？
是否对输入数据做了校验和清洗？

11. 小结

API 是现代软件世界的通用语言。理解 API 的工作原理，不只是为了写代码——它能帮你理解手机上的每一个 App 是如何运作的，帮你评估第三方服务的技术方案，帮你在产品开发和商业决策中做出更准确的判断。

从本文的核心要点出发：API 是前后端的契约，REST 是最主流的 API 设计风格，HTTP 方法表达操作语义，JSON 是数据交换的通用格式，认证机制保障通信安全。掌握了这些基础，你就可以自信地阅读任何 API 文档、调用任何 API 接口。

参考资料

MDN Web Docs - HTTP request methods — HTTP 方法的官方规范说明
AWS - What is RESTful API? — REST API 概念入门
IBM - What Is a REST API — REST API 详细定义与约束
freeCodeCamp - What is REST? Definition for Beginners — 面向初学者的 REST 教程
WorkOS - What Is API Authentication? — API 认证方式指南（OAuth 2.0、JWT、API Key）
OpenAI API Reference — OpenAI API 官方文档
Stripe API Reference — Stripe 支付 API 官方文档
RESTful API Design - restfulapi.net — REST API 设计最佳实践