概述

欢迎访问本 API 规范文档！以下是 API 的设计原则与使用规范：

  • 语言支持：当前页面为中文版，如需英文版请访问 /en/api_specification 🌐
  • 版本控制：当前版本 v1.0.0，可通过 /api_version 查看历史版本记录 📜
  • 安全要求：所有请求需通过 HTTPS 协议，未加密通信将被拒绝 🔒

核心规范

请求方法

方法 用途 示例
GET 获取资源 GET /api/data
POST 创建资源 POST /api/create
PUT 更新资源 PUT /api/update
DELETE 删除资源 DELETE /api/delete

路径结构

  • 基础路径：/api/ 为所有接口的根目录 🏡
  • 子路径规则：
    • /{resource}/{action}（如 /users/list）
    • /{resource}/id/{value}（如 /users/123）
  • 参数格式：支持查询参数（?key=value）与请求体（JSON 格式） 📦

响应格式

  • 成功响应：200 OK，数据以 JSON 返回 🎉
  • 错误响应：400-599，包含错误码与描述（如 404_Not_Found） ❌

使用示例

GET /api/data?format=json HTTP/1.1
Host: example.com
Accept: application/json

响应示例：

{
  "status": "success",
  "data": ["example1", "example2"],
  "timestamp": "2023-10-05T12:34:56Z"
}

扩展阅读

api_design