第2章 API基础概念

第2章：API基础概念

好，咱们直接进入正题。这一章讲的是API最基础的东西，说白了就是「接口到底是个啥」。我见过不少新手，一上来就调接口，结果连API是什么都没搞明白，出了问题一脸懵。咱们先把地基打牢。

2.1 API是什么？

API，全称是Application Programming Interface，应用程序编程接口。别被这个高大上的名字吓到。

我习惯这么理解：API就是两个软件之间约定的「对话方式」。

举个例子。你去餐厅吃饭，你不会直接冲进厨房抢厨师手里的锅。你会做什么？看菜单、点菜、等菜、吃菜、结账。这个过程中，菜单就是API——它规定了你能点什么、怎么点、点什么菜会得到什么结果。

放到程序里也一样：

你的程序是「顾客」
对方的服务是「厨房」
API就是那个「菜单」

你照着菜单点菜，厨房按菜单做菜。谁也别乱来，这就是API存在的意义。

核心要点：API的本质是「约定」。它约定了你能做什么、怎么做、会得到什么结果。

2.2 RESTful API简介

现在市面上最流行的API风格，就是RESTful API。我刚开始接触时也觉得这词玄乎，其实拆开看就明白了。

REST，Representational State Transfer，表现层状态转移。嗯，这翻译确实拗口。你记住一句话就行：RESTful API就是用HTTP协议的方法，来操作资源。

什么叫「操作资源」？说白了就是增删改查。HTTP协议给了我们几个现成的方法：

HTTP方法	操作	类比SQL	举个栗子
GET	获取资源	SELECT	获取用户列表
POST	创建资源	INSERT	新增一个用户
PUT	更新资源（全量）	UPDATE	修改用户全部信息
PATCH	更新资源（部分）	UPDATE	只修改用户手机号
DELETE	删除资源	DELETE	删除一个用户

你看，是不是很直观？每个方法对应一个操作，URL指向你要操作的资源。

举个例子，一个典型的RESTful API长这样：

# 获取所有用户
GET https://api.example.com/users

# 获取ID为123的用户
GET https://api.example.com/users/123

# 创建新用户
POST https://api.example.com/users
Content-Type: application/json

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

# 更新用户信息
PUT https://api.example.com/users/123
Content-Type: application/json

{
  "name": "张三丰",
  "email": "zhangsf@example.com"
}

# 删除用户
DELETE https://api.example.com/users/123

我的经验：设计RESTful API时，URL里只用名词，不要用动词。比如用/users而不是/getUsers。动词交给HTTP方法去表达。这个习惯我从入行就养成了，后来发现团队协作时特别省心。

2.3 API Key与鉴权机制

API建好了，总不能谁都能调吧？这就涉及到鉴权了。

最常见的鉴权方式就是API Key。说白了就是一个字符串，相当于你的「通行证」。

调用API时，你得把这个Key带上，服务端一看Key合法，才给你返回数据。

常见的传递方式有两种：

放在请求头里（推荐）
放在URL参数里（不推荐，容易被记录）

# 方式一：请求头传递（推荐）
GET https://api.example.com/users
Authorization: Bearer your-api-key-here

# 方式二：URL参数传递（不推荐）
GET https://api.example.com/users?api_key=your-api-key-here

注意：千万不要把API Key硬编码在代码里！我曾经见过有人直接把Key写在GitHub上公开的代码里，结果被爬虫扫到，一夜之间被刷了几十万次请求，账单直接爆炸。血的教训啊。

除了API Key，还有更复杂的鉴权方式，比如OAuth 2.0、JWT等。这些后面章节会细讲，这里先有个概念就行。

2.4 请求与响应模型

每次API调用，本质上就是一次「请求-响应」的往返。你发一个请求过去，对方给你一个响应回来。

一个标准的HTTP请求包含这几部分：

请求行：方法 + URL + HTTP版本
请求头：携带元信息，比如认证信息、内容类型等
请求体：携带实际数据（GET请求一般没有）

一个标准的HTTP响应包含这几部分：

状态行：HTTP版本 + 状态码 + 状态描述
响应头：携带元信息
响应体：返回的实际数据

看个完整的例子就清楚了：

// 请求
POST https://api.openai.com/v1/chat/completions
Authorization: Bearer sk-xxxxx
Content-Type: application/json

{
  "model": "gpt-3.5-turbo",
  "messages": [
    {"role": "user", "content": "你好"}
  ]
}

// 响应
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "你好！有什么可以帮助你的吗？"
      }
    }
  ]
}

这里有个关键点——状态码。我建议你把这几个常用的背下来：

状态码	含义	说明
200	OK	请求成功，一切正常
201	Created	创建成功（POST请求常见）
400	Bad Request	请求参数有误，你的锅
401	Unauthorized	没带Key或者Key不对
403	Forbidden	Key对了但没权限
404	Not Found	资源不存在
429	Too Many Requests	调用太频繁，被限流了
500	Internal Server Error	服务器炸了，对方的锅

避坑指南：调试API时，先看状态码，再看响应体。我见过太多人一上来就盯着响应体里的错误信息看半天，结果发现状态码是401——压根没通过认证。先看状态码，能帮你快速定位问题。

嗯，这一章的内容就到这儿。API基础概念看着简单，但真用起来坑不少。下一章咱们聊聊怎么用Python调API，手把手带你写第一个调用代码。

📚 课程目录