api 格式

API 格式详解

API 基础概念

API（Application Programming Interface）是应用程序之间的通信接口，允许不同系统或组件通过预定义的规则进行数据交换，常见类型包括 RESTful API、SOAP API、GraphQL API 等。

RESTful API 核心格式

RESTful API 是基于 HTTP 协议的轻量级接口，遵循 资源导向 的设计原则,以下是其核心格式：

请求方法（HTTP Method）

URL 结构

https://{域名}/{资源路径}?{查询参数}

• 路径参数：通过 URL 路径传递，如 /users/{id}。
• 查询参数：通过 后追加键值对，如 ?page=1&limit=10。

请求头（Headers）

请求参数

• 查询参数：附加在 URL 后，如 /users?age=20。
• 表单参数：application/x-www-form-urlencoded 格式，如 name=John&age=20。
• JSON 参数：application/json 格式，如：

  {
    "name": "John",
    "age": 20
  }

响应格式

• 状态码（Status Code）：
  • 2xx：成功（如 200 OK、201 Created）。
  • 4xx：客户端错误（如 400 Bad Request、404 Not Found）。
  • 5xx：服务器错误（如 500 Internal Server Error）。
• 响应头：
  • Content-Type：返回数据格式（如 application/json）。
  • Location：资源创建后的新地址（如 POST 成功后返回）。
• 响应体：
  • 通常为 JSON 格式，包含数据或错误信息。

    {
      "status": "success",
      "data": {
        "id": 123,
        "name": "John Doe"
      },
      "message": "User retrieved successfully"
    }

API 设计规范

资源命名

• 使用名词复数形式（如 /users）。
• 避免动词（如 /getUser 应改为 /users/{id}）。

状态码语义

错误响应格式

{
  "status": "error",
  "code": 404,
  "message": "Resource not found",
  "details": "The user with ID 123 does not exist."
}

常见问题与解答

问题 1：如何选择合适的 HTTP 方法？

解答：

• GET：仅用于获取数据，无副作用（如查询、列表）。
• POST：用于创建新资源。
• PUT：用于完全更新资源（需提供完整数据）。
• PATCH：用于部分更新资源（如修改单个字段）。
• DELETE：用于删除资源。

问题 2：API 返回错误时应该如何处理？

解答：

1. 检查状态码：根据状态码判断错误类型（如 4xx 是客户端问题，5xx 是服务器问题）。
2. 阅读错误信息：响应体中的 message 或 details 字段通常包含具体原因。
3. 重试机制：对于 5xx 错误，可尝试重新请求；对于 4xx

小伙伴们，上文介绍了“api 格式”的内容，你了解清楚吗？希望对你有所帮助，任何问题可以给我留言，让我们下期再见吧。