跳转至

API 与软件接口基础

1. 核心概念

概念 全称 / 含义 记忆要点
API Application Programming Interface,应用程序编程接口 软件对外提供的功能入口与交互契约
SDK Software Development Kit,软件开发工具包 帮助开发者使用某个平台或 API 的工具集合,常封装请求、认证、数据模型和错误处理
JSON JavaScript Object Notation 常见的数据交换格式
REST Representational State Transfer 一种常见的 API 架构风格
OpenAPI OpenAPI Specification 用 JSON/YAML 描述 HTTP API 的标准
Swagger UI OpenAPI 生态中的文档展示工具 将 OpenAPI 描述渲染成交互式文档,可试调用接口
  • API 定义“可以调用什么、按什么规则调用”,SDK 提供“更方便调用这些能力的工具”。
  • SDK 常基于 API 构建,但并非每个 API 都有 SDK;API 也不局限于 HTTP,API 是一种协议,关键思想是把一层操作黑箱化,外部调用者只需知道怎么用,怎么调,返回数据是怎样的。

2. 一个 HTTP API 请求由什么组成?

示例:

GET https://api.example.com/v1/videos/123
Authorization: Bearer YOUR_API_KEY
Accept: application/json
组成 含义 示例
Scheme 协议 https://
Host 主机 / 域名 api.example.com
Base URL 多个接口共用的基础地址 https://api.example.com/v1
Path / Endpoint 资源路径或具体接口路径 /videos/123
HTTP Method 请求方法 GET
Path Parameter 路径参数,通常标识具体资源 /videos/{id} 中的 id
Query Parameter 查询参数,通常用于筛选、排序、分页 ?page=1&limit=20
Header 请求头,携带认证、内容类型等元信息 Authorization
Request Body 请求体,通常用于提交数据 JSON 对象

常见 HTTP Method

Method 常见用途
GET 获取资源
POST 创建资源或提交操作
PUT 整体替换资源
PATCH 部分修改资源
DELETE 删除资源

Request / Response

  • Request(请求):客户端发给服务器的内容。
  • Response(响应):服务器返回给客户端的内容。
  • Response 通常包含 HTTP 状态码、Headers 和 Body。

常见状态码:

状态码 含义
200 成功
201 创建成功
204 成功,无响应内容
400 请求不合法
401 未通过认证
403 没有访问权限
404 资源不存在
429 请求过于频繁
500 服务器内部错误
503 服务暂时不可用

3. API 文档

API 文档是 API 的使用说明与技术契约,通常说明:

  • Base URL、Endpoint、HTTP Method
  • Path / Query Parameters
  • Headers、认证方式
  • Request Body 的字段、类型和约束
  • Response 的结构与示例
  • 错误码、分页、频率限制等行为

常见载体:

  • Markdown / HTML:方便人阅读。
  • OpenAPI JSON / YAML:机器可读,可用于生成文档、客户端代码和测试辅助工具。
  • OpenAPI 与 Swagger:
  • OpenAPI 是描述 HTTP API 的规范。
  • Swagger 是围绕 OpenAPI 的工具生态;Swagger UI 可展示并试调用接口。

4. 常见工程概念

概念 含义
Authentication(认证) 确认“你是谁”
Authorization(授权) 判断“你能做什么”
API Key / Bearer Token 常见的 API 访问凭证形式
Pagination(分页) 分批获取大量数据;常见方式有页码分页和游标分页
Rate Limiting(频率限制) 限制单位时间内的请求数量;超限常返回 429
Versioning(版本管理) 例如 /v1、/v2,用于管理接口演进与兼容性
Error Handling(错误处理) 通过状态码和结构化错误信息让客户端识别问题
Idempotency(幂等性) 同一操作重复执行,最终效果与执行一次相同
Webhook 事件发生时,服务端主动向预先配置的 URL 发送通知
API Gateway API 网关,常用于统一入口、路由、认证、限流等
  • API Key / Token 不应泄露在公开前端代码、仓库或日志中。
  • GET、PUT、DELETE 按 HTTP 语义具有幂等性(Idempotency);POST 通常不具有。具体业务也可能通过 Idempotency Key 实现重复请求保护:也就是多次重复操作与执行一次的结果一致。
  • 重试请求时要考虑网络错误、状态码、退避策略,以及操作是否幂等。

5. REST 与 GraphQL

  • REST:常以资源为中心,通过多个 Endpoint 和 HTTP Method 表达操作。
  • GraphQL:客户端通过 Query / Mutation 声明需要的字段或执行的操作,常通过一个 GraphQL Endpoint 提供服务。
  • 两者是不同的 API 设计方式,应根据业务需求选择。

6. 前后端分离中的 API

典型关系:

Web / Desktop / Mobile Client
            |
         HTTP API
            |
       Backend Server
            |
         Database
  • 前端:UI、用户交互。
  • 后端:业务逻辑、权限验证、数据处理。
  • 数据库:持久化存储。
  • API:客户端与服务端之间的通信契约。

同一套后端 API 可以服务多个客户端。提前约定 API 契约,可以让前后端并行开发,减少联调时的字段、参数和行为不一致。

7. C# / .NET 中的最小例子

服务端定义 Endpoint:

app.MapGet("/api/videos/{id}", (int id) =>
{
    var video = new
    {
        Id = id,
        Title = "Learn Programming",
        Views = 15200
    };

    return Results.Ok(video);
});

客户端调用:

using System.Net.Http.Json;

var client = new HttpClient();

var video = await client.GetFromJsonAsync<Video>(
    "https://localhost:5001/api/videos/123"
);

public class Video
{
    public int Id { get; set; }
    public string Title { get; set; }
    public int Views { get; set; }
}
  • HttpClient:发送 HTTP 请求。
  • GetFromJsonAsync<T>:发送 GET 请求并将 JSON 反序列化为 C# 对象。
  • Video:客户端用于承接响应数据的数据模型。

  • curl:命令行请求工具。

快速测试:

curl https://api.example.com/v1/videos/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

一句话总结

  • API:定义软件之间如何交互。
  • OpenAPI:描述 HTTP API 契约。
  • Swagger UI:展示和试调用 API 文档。
  • SDK:降低开发者调用 API 的成本。
  • REST:设计 API 的一种常见架构风格。 ```