API 概览

我们的 REST API 提供了完整的平台功能访问接口。所有 API 端点都使用 HTTPS 协议，支持 JSON 格式的请求和响应数据。

基础信息

基础 URL：https://api.example.com/v2
协议：HTTPS
数据格式：JSON
字符编码：UTF-8

版本说明：当前文档描述的是 API v2 版本。v1 版本将在 2024年6月30日后停止支持。

身份认证

API 使用 Bearer Token 进行身份认证。您需要在每个请求的 Header 中包含访问令牌：

Authorization: Bearer YOUR_ACCESS_TOKEN

获取访问令牌

通过以下端点获取访问令牌：

POST /auth/token
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your_password"
}

成功响应：

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200..."
}

安全提醒：请妥善保管您的访问令牌，不要在客户端代码中硬编码令牌。

请求限制

为了保证服务质量，API 实施了请求频率限制：

用户类型	每分钟请求数	每小时请求数	每日请求数
免费用户	60	1,000	10,000
付费用户	300	10,000	100,000
企业用户	1,000	50,000	1,000,000

当超过限制时，API 将返回 429 Too Many Requests 状态码。

响应格式

所有 API 响应都遵循统一的格式：

成功响应

{
  "success": true,
  "data": {
    // 实际数据内容
  },
  "meta": {
    "timestamp": "2024-01-20T10:30:00Z",
    "request_id": "req_123456789"
  }
}

错误响应

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "请求参数验证失败",
    "details": [
      {
        "field": "email",
        "message": "邮箱格式不正确"
      }
    ]
  },
  "meta": {
    "timestamp": "2024-01-20T10:30:00Z",
    "request_id": "req_123456789"
  }
}

状态码

API 使用标准的 HTTP 状态码：

状态码	含义	说明
`200`	OK	请求成功
`201`	Created	资源创建成功
`400`	Bad Request	请求参数错误
`401`	Unauthorized	未授权访问
`403`	Forbidden	禁止访问
`404`	Not Found	资源不存在
`429`	Too Many Requests	请求过于频繁
`500`	Internal Server Error	服务器内部错误

用户管理 API

获取用户信息

获取当前登录用户的详细信息。

GET /users/me
Authorization: Bearer YOUR_ACCESS_TOKEN

响应示例：

{
  "success": true,
  "data": {
    "id": "user_123456",
    "email": "user@example.com",
    "name": "张三",
    "avatar": "https://cdn.example.com/avatars/user_123456.jpg",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-20T10:30:00Z",
    "subscription": {
      "plan": "pro",
      "expires_at": "2024-12-31T23:59:59Z"
    }
  }
}

更新用户信息

更新当前用户的个人信息。

PUT /users/me
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "name": "李四",
  "bio": "产品经理"
}

上传头像

上传用户头像图片。

POST /users/me/avatar
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: multipart/form-data

avatar: [图片文件]

项目管理 API

获取项目列表

获取当前用户的所有项目。

GET /projects?page=1&limit=20&sort=created_at&order=desc
Authorization: Bearer YOUR_ACCESS_TOKEN

查询参数：

page（可选）：页码，默认为 1
limit（可选）：每页数量，默认为 20，最大 100
sort（可选）：排序字段，可选值：name、created_at、updated_at
order（可选）：排序方向，可选值：asc、desc

创建项目

创建一个新项目。

POST /projects
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "name": "我的新项目",
  "description": "项目描述",
  "template": "blank",
  "settings": {
    "public": false,
    "allow_comments": true
  }
}

获取项目详情

获取指定项目的详细信息。

GET /projects/{project_id}
Authorization: Bearer YOUR_ACCESS_TOKEN

更新项目

更新项目信息。

PUT /projects/{project_id}
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "name": "更新后的项目名称",
  "description": "更新后的描述"
}

删除项目

删除指定项目。

DELETE /projects/{project_id}
Authorization: Bearer YOUR_ACCESS_TOKEN

警告：删除项目是不可逆操作，请谨慎使用。

Webhooks

Webhooks 允许您在特定事件发生时接收 HTTP 回调。

支持的事件

project.created - 项目创建
project.updated - 项目更新
project.deleted - 项目删除
user.updated - 用户信息更新

配置 Webhook

POST /webhooks
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "url": "https://your-app.com/webhook",
  "events": ["project.created", "project.updated"],
  "secret": "your_webhook_secret"
}

SDK 和示例

我们提供了多种编程语言的 SDK 来简化 API 集成：

JavaScript 示例

import { ApiClient } from '@example/api-client';

const client = new ApiClient({
  baseURL: 'https://api.example.com/v2',
  accessToken: 'YOUR_ACCESS_TOKEN'
});

// 获取用户信息
const user = await client.users.me();
console.log(user);

// 创建项目
const project = await client.projects.create({
  name: '我的项目',
  description: '项目描述'
});
console.log(project);

API 参考文档