API 方法全解析｜RESTful 开发者入门与最佳实践

一. API 方法：开发者入门指南

在开发过程中，你是否曾纠结于某些接口设计的细节，比如 重发短信通知的端点究竟应该使用 POST 还是 GET？或许你会认为：“既然不需要请求体，那肯定是 GET 请求。”但请注意，这种假设是错误的。

本指南将帮助你系统了解 REST API 的常见方法及其应用场景。我们将深入探讨“增删改查”操作、HTTP 请求类型的核心特性（如 幂等性、安全性和可缓存性），并介绍不同类型的 API 调用方式。

二. 什么是 API 方法？

API 方法是理解 API 运作机制的基础。每次发送 HTTP 请求时，都需要指定方法以明确请求的功能。服务器会根据所选方法决定如何响应请求，并通常以 JSON 或 XML 等格式返回数据。这种 请求-响应模型 是 API 交互的核心。

三. API 方法的核心特性

在讨论 API 方法时，需要重点关注以下三大特性：

1. 安全性

安全方法不会修改服务器资源，允许客户端无风险地访问资源。

2. 幂等性

幂等方法可重复调用，且效果与首次调用一致，确保客户端能够安全地重试请求。

3. 可缓存性

可缓存方法的响应可以被存储和复用，从而显著提升 API 性能。

四. 常见 API 请求类型

以下是 RESTful API 应用中最常用的 HTTP 方法及其应用场景。

1. GET 方法

a. 应用场景

用于无副作用的数据获取，是 REST API 中最常见的操作。

GET 方法专用于从服务器检索目标资源数据，具有幂等性、安全性和可缓存性。
例如，使用 Pieces REST API 的 /models 端点可以获取可下载的 AI 模型列表。本地安装 Pieces 后，通过端口 39301 查询该端点，服务器会以 JSON 格式返回所有 AI 模型的数据。

2. POST 方法

a. 应用场景

用于创建新资源或提交需要改变状态的数据，也可触发服务端的副作用。

POST 方法主要用于数据创建或触发某些操作（如发送邮件）。
例如，重发验证邮件时，即使不带请求体，也应使用 POST 而非 GET，因为该操作会产生副作用。需要注意的是，POST 方法既非幂等也非安全，但可以通过显式设置缓存头实现可缓存性。

3. PUT 方法

a. 应用场景

用于完整更新或替换现有资源。

PUT 方法通常用于替换已知 URI 的资源或更新由客户端指定 ID 的数据。例如，将文件上传至 Amazon S3 存储或更新用户头像。PUT 方法会修改服务器状态，因此它既非安全也不可缓存，但具有幂等性——重复上传文件会持续替换同一对象。

4. DELETE 方法

a. 应用场景

用于删除服务器上的资源。

DELETE 方法用于移除资源，完成 CRUD 操作的闭环。它具有幂等性（多次删除同一资源的结果一致），但既不安全也不可缓存。例如，删除自定义模型后，重复请求会返回 404 状态码，但最终状态保持一致。

5. PATCH 方法

a. 应用场景

用于对资源进行局部更新。

当只需对资源进行微小修改时，使用 PATCH 方法比 PUT 更高效，因为它避免了传输整个资源的开销。PATCH 方法会修改资源状态，因此它非安全，通常也不具幂等性（除非更新为固定值）。

6. OPTIONS 方法

a. 应用场景

用于探测端点支持的通信选项。

OPTIONS 方法用于获取特定资源支持的 HTTP 方法和头部信息，在 CORS（跨域资源共享） 中尤为重要。该方法是安全且幂等的，但不可缓存。

7. HEAD 方法

a. 应用场景

用于仅获取元数据。

HEAD 方法与 GET 类似，但只返回头部信息，不包含响应体。它同样具备幂等性、安全性和可缓存性。

五. 其他 HTTP 方法

• CONNECT：通过代理建立 HTTPS 连接，通常由 Nginx 等反向代理自动处理。
• TRACE：用于诊断请求路径，可检测代理或网关的请求篡改。

六. 新兴 QUERY 方法

QUERY 方法是为了解决 GET 请求参数过长的问题而提出的。它在保留 GET 方法优点的同时，支持类似 POST 的参数传递方式，目前已成为 提案标准。

七. API 类型全景

除了 REST API 外，还有多种 API 范式：

• SOAP：基于 XML 的消息协议。
• GraphQL：一种允许客户端精准获取所需数据的查询语言。
• RPC：远程过程调用。
• Webhook：用于实时推送数据的反向 API。
• 开放/合作/内部/组合 API：满足不同协作需求的 API 类型。

八. 总结

API 方法是通用的构造，其具体行为取决于实现方式。尽管 REST 原则为开发者提供了指导，但在实际应用中可以灵活运用（例如，用 DELETE 方法创建数据）。

开发者可以结合工具（如 Gin 和 Swagger）构建高效的 API，并不断探索 API 的更多可能性。

原文链接: https://pieces.app/blog/practical-guide-api-methods