API接口是什么？一文读懂API的定义、原理、类型与实战应用

API是接口规范，定义了如何与某个系统交互；SDK（软件开发工具包）则是包含API、开发工具、文档和示例代码的集合。简单来说，API是“菜单”，SDK是“全套厨具+食材+菜谱”。例如，微信支付API让你能够调用支付功能，而微信支付SDK则提供了封装好的库，让你更方便地集成。通常SDK内部包含了API调用，但API可以独立存在。

GET和POST是HTTP协议中最常用的两种方法。GET用于获取资源，通常不改变服务器状态，参数通过URL传递，有长度限制，且会被浏览器缓存；POST用于提交数据，可能创建或修改资源，数据放在请求体中，更安全，没有长度限制。例如，获取用户列表用GET /users，创建新用户用POST /users。在RESTful设计中，GET应保持幂等（多次调用结果相同），而POST则不一定。

常见的API身份验证方式有：

1. API Key：在请求头或URL中添加密钥，简单但不够安全，适合低风险场景。
2. OAuth 2.0：开放授权协议，允许用户授权第三方应用访问其数据，如“使用微信登录”。
3. JWT（JSON Web Token）：服务器签发加密令牌，客户端每次请求携带，无状态且可扩展。
4. 基本认证：用户名密码的Base64编码，必须配合HTTPS使用。选择哪种方式取决于安全需求和场景。

HTTP状态码分为五类：

• 1xx：信息响应，如100 Continue。
• 2xx：成功，如200 OK、201 Created、204 No Content。
• 3xx：重定向，如301 Moved Permanently、304 Not Modified。
• 4xx：客户端错误，如400 Bad Request、401 Unauthorized、403 Forbidden、404 Not Found、429 Too Many Requests。
• 5xx：服务器错误，如500 Internal Server Error、503 Service Unavailable。开发者应正确处理这些状态码，如遇到401应重新认证，遇到429应等待重试。

API网关是位于客户端和后端服务之间的中间层，负责请求路由、聚合、认证、限流、监控等。它类似于“门卫”，统一处理所有API请求。主要作用包括：

1. 统一入口：客户端只需访问网关，无需知道后端服务地址。
2. 安全控制：集中实施认证、授权、IP白名单。
3. 流量管理：限流、熔断、负载均衡。
4. 协议转换：将HTTP请求转换为内部gRPC或AMQP协议。
5. 监控分析：记录日志、指标。常见的网关有Kong、Zuul、Spring Cloud Gateway。

设计易用的API需遵循以下原则：

1. 资源命名清晰：用名词复数表示资源，如 /users，避免动词。
2. 使用标准HTTP方法：GET、POST、PUT、DELETE对应查、增、改、删。
3. 返回有意义的错误：使用标准状态码，并在响应体中提供错误码和描述。
4. 支持分页和过滤：对列表资源提供 ?limit=10&offset=20 或 ?sort=name。
5. 提供完整的文档：包括示例、参数说明、错误码。
6. 版本管理：如 /v1/users，避免破坏性变更。
7. 使用JSON：作为默认数据格式，并支持HATEOAS（可选）。

速率限制是指API提供商对客户端在一定时间内的请求次数进行限制。例如，每分钟最多100次请求。主要目的是：

1. 防止滥用：避免单个用户占用过多资源，保护服务器稳定性。
2. 安全防护：减缓暴力破解和DDoS攻击。
3. 成本控制：对于按调用计费的API，限制用户消费。
4. 保证公平性：让所有用户都能享受服务。常见的实现方式有令牌桶、漏桶算法。当超过限制时，服务器返回429状态码，并可能在响应头中包含 Retry-After 字段。

OpenAPI规范（OAS）是一种用于描述HTTP API的标准格式，基于JSON或YAML，定义API的端点、参数、响应、认证方式等。Swagger是SmartBear公司开发的一套工具集，包括Swagger UI（可视化文档）、Swagger Editor（编辑规范）等。2015年，Swagger规范被捐赠给Linux基金会，更名为OpenAPI规范。所以，Swagger是工具，OpenAPI是规范。开发者可以使用Swagger工具来生成和展示OpenAPI文档，实现API的自动化文档、代码生成和测试。