什么是API？零基础入门

一、API 是什么

API（Application Programming Interface，应用程序编程接口）这个词听起来很高级，但本质非常简单：API 就是软件之间"对话的约定"。

最直观的比喻是餐厅点菜：

1. 你（调用方）看着菜单（API 文档），选择"宫保鸡丁"
2. 你把订单交给服务员（API 调用）
3. 服务员把订单送到后厨（服务器）
4. 后厨做好菜，服务员端给你（API 响应）

你不需要知道后厨怎么切菜、怎么炒——你只需要知道"点这个菜，会得到这个菜"。API 也是一样：你不需要知道服务器内部怎么实现，只需要知道"调用这个接口，传这些参数，会得到这种结果"。

二、Web API 是什么

互联网上最常见的 API 是 Web API（也叫 HTTP API）：通过 HTTP 协议在网络上交换数据。几乎所有手机 App、网站、SaaS 服务背后都有 Web API。

一个典型的 API 调用长这样：

请求：

GET https://api.example.com/users/123
Authorization: Bearer eyJhbGc...

响应：

{
  "id": 123,
  "name": "张三",
  "email": "zhangsan@example.com"
}

这就是一次完整的 API 调用：客户端用 GET 方法请求一个 URL，服务器返回 JSON 数据。

三、HTTP 方法

HTTP 协议定义了几种方法（也叫动词），对应不同的操作：

"幂等"的意思是：同一个请求执行一次和执行多次，效果相同。GET 是幂等的（查多少次结果都一样），POST 不是（提交两次会创建两条记录）。

实际例子

# 获取用户列表
GET /users

# 获取单个用户
GET /users/123

# 创建用户
POST /users
Body: { "name": "张三", "email": "..." }

# 更新用户（整体替换）
PUT /users/123
Body: { "name": "李四", "email": "..." }

# 部分更新用户
PATCH /users/123
Body: { "name": "李四" }

# 删除用户
DELETE /users/123

四、RESTful 风格

REST（Representational State Transfer）是 Roy Fielding 在 2000 年博士论文中提出的一种 API 设计风格。符合这种风格的 API 叫 RESTful API。

RESTful 的核心原则：

1. 用 URL 表示资源

资源用名词，不用动词：

2. 用 HTTP 方法表示动作

URL 表示"是什么"，HTTP 方法表示"做什么"。这是 RESTful 和传统 RPC 风格最大的区别。

3. 用状态码表示结果

服务器返回合适的 HTTP 状态码，让客户端能从状态码判断结果。

4. 无状态

每个请求自带所有必要信息（认证、参数），服务器不依赖 session 状态。这样便于水平扩展。

RESTful API 完整示例

GET    /articles              # 获取文章列表
POST   /articles              # 创建文章
GET    /articles/123          # 获取某篇文章
PUT    /articles/123          # 更新文章
DELETE /articles/123          # 删除文章
GET    /articles/123/comments # 获取某篇文章的评论
POST   /articles/123/comments # 给某篇文章加评论

URL 的层级关系表达了资源的从属关系，非常直观。

五、HTTP 状态码

状态码是服务器对请求结果的"快速答复"，分五类：

最常用的几个：

一个常见误区：把所有错误都返回 200，然后在 body 里写 {"code": 404, "msg": "..."}。这违反了 HTTP 语义，不建议这样设计。

六、JSON 数据格式

现代 API 几乎都用 JSON 作为数据交换格式。一个完整的请求和响应示例：

请求：

POST /api/articles HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer xxx

{
  "title": "API 入门",
  "content": "今天学习 API...",
  "tags": ["编程", "入门"]
}

响应：

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 456,
  "title": "API 入门",
  "content": "今天学习 API...",
  "tags": ["编程", "入门"],
  "author": { "id": 1, "name": "张三" },
  "createdAt": "2026-07-29T10:00:00Z"
}

为什么用 JSON 而不是 XML？

JSON 在 Web API 领域已经全面胜出。

七、API 鉴权

API 通常需要知道"调用者是谁、有没有权限"。常见的鉴权方式：

1. API Key

最简单的方式：调用方在请求里带一个固定的 key。

GET /api/data?api_key=abc123
# 或
GET /api/data
X-API-Key: abc123

适合后端到后端调用，不适合前端（key 会暴露）。

2. Bearer Token（JWT）

用户登录后拿到一个 token，之后每个请求带上：

GET /api/profile
Authorization: Bearer eyJhbGc...

这是目前最主流的方式，token 通常用 JWT 格式。

3. OAuth 2.0

用于第三方授权，比如"用微信登录"、"用 GitHub 登录"。流程比较复杂，但安全性最高。

4. Basic Auth

把用户名密码用 Base64 编码后发送：

Authorization: Basic dXNlcjpwYXNz

简单但不安全，密码每次都要传，现在很少用。

八、常见 API 实例

1. 天气查询 API

GET https://api.weather.com/v1/forecast?city=beijing&key=xxx

响应：
{
  "city": "北京",
  "temperature": 28,
  "weather": "晴",
  "humidity": 60
}

2. 发送短信 API

POST /sms/send
Body: { "phone": "13800138000", "message": "您的验证码是 1234" }

响应：
{ "success": true, "messageId": "msg_001" }

3. AI 对话 API

POST /chat
Body: {
  "model": "gpt-4",
  "messages": [
    { "role": "user", "content": "你好" }
  ]
}

响应：
{
  "reply": "你好！有什么可以帮你的？"
}

九、调用 API 的几种方式

命令行 curl

curl -X GET https://api.example.com/users/123 \
  -H "Authorization: Bearer xxx"

浏览器 fetch

const res = await fetch("https://api.example.com/users/123", {
  headers: { "Authorization": "Bearer xxx" }
});
const data = await res.json();
console.log(data);

Python requests

import requests

res = requests.get(
    "https://api.example.com/users/123",
    headers={"Authorization": "Bearer xxx"}
)
print(res.json())

Node.js axios

const axios = require("axios");
const res = await axios.get("https://api.example.com/users/123", {
  headers: { Authorization: "Bearer xxx" }
});
console.log(res.data);

十、API 文档

好的 API 必须有清晰的文档。常见的 API 文档工具：

文档里通常包含：接口路径、方法、参数、请求示例、响应示例、错误码。

十一、实践推荐

学习和调试 API 时，最常用的操作就是"看 JSON 返回了什么"——无论是自己调接口、还是排查第三方 API 返回的数据，格式化 JSON 都是高频需求：

• JSON 格式化工具：https://52tool.net/tools/devtool/jsonFormat

把 API 返回的压缩 JSON 粘进去，一键得到带缩进、带语法高亮、带错误提示的版本，排查接口问题效率立竿见影。支持格式化、压缩、转义、校验，是 API 调试时最常打开的工具之一。