Skip to content

API

理解 API——应用程序之间如何对话，以及 REST API 如何组织请求与响应。

你将学到

  • API 是什么、为什么存在
  • REST API 如何在资源上使用 HTTP 方法
  • 端点是什么、如何调用
  • 认证如何保护 API 访问

概念讲解

API

API（Application Programming Interface，应用程序编程接口）是一套让一个软件与另一个软件对话的规则。不是用户点按钮，而是*程序*发请求、收数据。天气 App 显示预报时，就是调用了一个天气 API 取数据。

REST API

REST（Representational State Transfer）是 Web 上最常见的 API 风格。REST 把一切视为由 URL 标识的资源，用 HTTP 方法对它们操作：

| 方法 + URL | 动作 | |--------------|--------| | GET /users | 列出所有用户 | | GET /users/42 | 取单个用户 | | POST /users | 创建用户 | | PUT /users/42 | 替换用户 42 | | DELETE /users/42 | 删除用户 42 |

这种"HTTP 方法映射到 CRUD（建、查、改、删）"的关系就是 REST 的核心。

端点

端点是 API 暴露的某个具体 URL。https://api.example.com/users 就是一个端点。端点 + 方法共同定义一个操作。文档会列出所有端点、参数和响应结构。

调用 API

const response = await fetch("https://api.example.com/users/42", {
  headers: { "Authorization": "Bearer my-token" }
});
const user = await response.json();

认证

多数 API 要求认证——证明你有权访问。常见方式：

  • API key —— 放在头或查询参数里的秘密字符串。
  • Bearer 令牌 / JWT —— 签名令牌，证明你的身份和权限。
  • OAuth —— 让用户在不分享密码的情况下授权第三方访问。

没有认证，任何人都能读写任何用户的数据。理解如何认证是用真实 API 的必备知识。

示例代码

              // 调用 REST API 列出并创建用户
const API_BASE = "https://api.example.com";
const token = "your-api-token";

// GET：列出用户
async function listUsers() {
  const res = await fetch(`${API_BASE}/users`, {
    headers: { "Authorization": `Bearer ${token}` }
  });
  return res.json();
}

// POST：创建新用户
async function createUser(name, email) {
  const res = await fetch(`${API_BASE}/users`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ name, email })
  });
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  return res.json();
}

两次调用都用 Authorization 头带 bearer 令牌。GET 无请求体；POST 发 JSON。检查 res.ok 确保失败时抛错，而非静默返回错误对象。

动手试一试

  • JWT Decoder

    API 常用 JWT 做认证。解码一个看声明（用户 ID、过期、角色）。

  • JSON Schema Validator

    API 用 JSON Schema 定义响应结构。拿一个响应对照校验。

常见错误

错误写法

把 API key 硬编码进客户端代码。

正确做法

客户端代码人人可见。把 key 放服务器或代理后面。若必须放客户端，用受限且限速的 key。

错误写法

以为 fetch() 在 404 或 500 时会抛错。

正确做法

fetch 只在网络故障时 reject。HTTP 错误（4xx、5xx）仍会 resolve——必须手动检查 response.ok 或 response.status 并抛错。

相关资源

相关指南

练习 API

2 个练习

练习 API

查阅不认识的术语

新手友好的术语表用大白话解释编程术语——变量、函数、DOM、Promise 等等。

查看术语表

动手做项目

通过引导式项目应用所学，含起始代码与解决方案。

查看项目

解读错误信息

用大白话解释常见错误——什么意思、为什么发生、如何修复。

查看错误