192 lines
4.0 KiB
Markdown
192 lines
4.0 KiB
Markdown
---
|
||
title: REST API 完整参考
|
||
description: 200+ 标准接口文档，覆盖用户、内容、AI、支付等全部模块。
|
||
category: api
|
||
order: 1
|
||
---
|
||
|
||
# REST API 完整参考
|
||
|
||
> 200+ 标准接口文档，覆盖用户、内容、AI、支付等全部模块。
|
||
|
||
## 📚 API 概览
|
||
|
||
**基础 URL：** `https://api.websopy.com/v1`
|
||
|
||
**认证方式：** Bearer Token
|
||
|
||
```bash
|
||
curl -H "Authorization: Bearer YOUR_API_KEY" \
|
||
https://api.websopy.com/v1/user/profile
|
||
```
|
||
|
||
## 📋 端点列表
|
||
|
||
### 用户管理 `/user`
|
||
|
||
| 方法 | 端点 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/user/profile` | 获取当前用户信息 |
|
||
| PUT | `/user/profile` | 更新用户信息 |
|
||
| GET | `/user/settings` | 获取用户设置 |
|
||
| PUT | `/user/settings` | 更新用户设置 |
|
||
| POST | `/user/avatar` | 上传头像 |
|
||
|
||
### 项目管理 `/projects`
|
||
|
||
| 方法 | 端点 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/projects` | 列出项目 |
|
||
| POST | `/projects` | 创建项目 |
|
||
| GET | `/projects/:id` | 获取项目详情 |
|
||
| PUT | `/projects/:id` | 更新项目 |
|
||
| DELETE | `/projects/:id` | 删除项目 |
|
||
| GET | `/projects/:id/members` | 获取项目成员 |
|
||
| POST | `/projects/:id/members` | 添加成员 |
|
||
|
||
### 文件存储 `/storage`
|
||
|
||
| 方法 | 端点 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/storage/files` | 列出文件 |
|
||
| POST | `/storage/upload` | 上传文件 |
|
||
| GET | `/storage/files/:id` | 获取文件信息 |
|
||
| DELETE | `/storage/files/:id` | 删除文件 |
|
||
| GET | `/storage/files/:id/download` | 下载文件 |
|
||
|
||
### AI 功能 `/ai`
|
||
|
||
| 方法 | 端点 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/ai/chat` | 发送对话请求 |
|
||
| POST | `/ai/chat/stream` | 流式对话 |
|
||
| GET | `/ai/sessions` | 列出会话 |
|
||
| POST | `/ai/sessions` | 创建会话 |
|
||
| GET | `/ai/sessions/:id` | 获取会话详情 |
|
||
| DELETE | `/ai/sessions/:id` | 删除会话 |
|
||
| POST | `/ai/knowledge` | 创建知识库 |
|
||
| POST | `/ai/knowledge/:id/documents` | 添加文档 |
|
||
|
||
### 支付 `/payments`
|
||
|
||
| 方法 | 端点 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/payments/orders` | 列出订单 |
|
||
| POST | `/payments/orders` | 创建订单 |
|
||
| GET | `/payments/orders/:id` | 订单详情 |
|
||
| POST | `/payments/checkout` | 创建结算会话 |
|
||
| GET | `/payments/subscriptions` | 订阅列表 |
|
||
|
||
## 🔍 请求与响应
|
||
|
||
### 请求头
|
||
|
||
```http
|
||
Authorization: Bearer YOUR_API_KEY
|
||
Content-Type: application/json
|
||
Accept: application/json
|
||
X-Request-ID: unique-request-id
|
||
```
|
||
|
||
### 分页
|
||
|
||
```http
|
||
GET /projects?page=2&limit=20
|
||
```
|
||
|
||
响应包含分页信息：
|
||
|
||
```json
|
||
{
|
||
"data": [...],
|
||
"pagination": {
|
||
"page": 2,
|
||
"limit": 20,
|
||
"total": 100,
|
||
"total_pages": 5
|
||
}
|
||
}
|
||
```
|
||
|
||
### 排序
|
||
|
||
```http
|
||
GET /projects?sort=created_at&order=desc
|
||
```
|
||
|
||
### 过滤
|
||
|
||
```http
|
||
GET /projects?status=active&category=ai
|
||
```
|
||
|
||
## 📝 错误处理
|
||
|
||
### 错误码
|
||
|
||
| 状态码 | 错误码 | 说明 |
|
||
|--------|--------|------|
|
||
| 400 | `INVALID_REQUEST` | 请求参数错误 |
|
||
| 401 | `UNAUTHORIZED` | 未认证或 Token 无效 |
|
||
| 403 | `FORBIDDEN` | 无权限访问 |
|
||
| 404 | `NOT_FOUND` | 资源不存在 |
|
||
| 429 | `RATE_LIMITED` | 请求过于频繁 |
|
||
| 500 | `SERVER_ERROR` | 服务器内部错误 |
|
||
|
||
### 错误响应格式
|
||
|
||
```json
|
||
{
|
||
"error": {
|
||
"code": "INVALID_REQUEST",
|
||
"message": "参数 'name' 不能为空",
|
||
"details": {
|
||
"field": "name",
|
||
"constraint": "required"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🔧 使用示例
|
||
|
||
### JavaScript/TypeScript
|
||
|
||
```typescript
|
||
const response = await fetch('https://api.websopy.com/v1/projects', {
|
||
method: 'POST',
|
||
headers: {
|
||
'Authorization': `Bearer ${apiKey}`,
|
||
'Content-Type': 'application/json'
|
||
},
|
||
body: JSON.stringify({
|
||
name: '我的项目',
|
||
description: '项目描述'
|
||
})
|
||
})
|
||
|
||
const data = await response.json()
|
||
console.log(data)
|
||
```
|
||
|
||
### Python
|
||
|
||
```python
|
||
import requests
|
||
|
||
response = requests.post(
|
||
'https://api.websopy.com/v1/projects',
|
||
headers={
|
||
'Authorization': f'Bearer {api_key}',
|
||
'Content-Type': 'application/json'
|
||
},
|
||
json={
|
||
'name': '我的项目',
|
||
'description': '项目描述'
|
||
}
|
||
)
|
||
|
||
data = response.json()
|
||
print(data)
|
||
```
|