chatserver/API.md

# API 文档

## 基础信息
- **基础 URL**: `http://localhost:5000/api`
- **数据格式**: JSON

## 认证方式
使用简单的 Token 认证（实际生产环境应使用 JWT 等更安全的方式）。  
登录后返回的 Token 需在后续请求中通过 `Authorization` 头携带：  `Authorization: Bearer <your_token>`


---

## API 端点

### 1. 用户注册
**URL**: `/register`  
**方法**: POST  
**请求体**:
```json
{
    "username": "string",
    "password": "string"
}
```

**成功响应**:
```json
{
    "success": true,
    "message": "User registered successfully"
}
```
**错误响应**:
```json
{
    "success": false,
    "message": "Username already exists"
}
```


---

### 2. 用户登录
**URL**: `/login`  
**方法**: POST  
**请求体**:
```json
{
    "username": "string",
    "password": "string"
}
```

**成功响应**:
```json
{
    "success": true,
    "message": "Login successful",
    "token": "string",
    "user_id": "integer",
    "username": "string"
}
```
**错误响应**:
```json
{
    "success": false,
    "message": "Invalid username or password"
}
```


---

### 3. 获取用户列表
**URL**: `/users`  
**方法**: GET  
**成功响应**:
```json
{
    "success": true,
    "users": [
        {
            "id": "integer",
            "username": "string",
            "is_online": "boolean",
            "last_login": "string"
        }
    ]
}
```

---

### 4. 获取消息历史
**URL**: `/messages`  
**方法**: GET  
**查询参数**:
- `user_id` (必填): 当前用户ID
- `other_id` (必填): 聊天对象用户ID
- `limit` (可选): 返回消息数量限制（默认 100）

**成功响应**:
```json
{
    "success": true,
    "messages": [
        {
            "id": "integer",
            "sender_id": "integer",
            "receiver_id": "integer",
            "content": "string",
            "timestamp": "string",
            "is_recalled": "boolean",
            "sender_name": "string",
            "receiver_name": "string"
        }
    ]
}
```


---

### 5. 撤回消息
**URL**: `/recall_message`  
**方法**: POST  
**请求体**:
```json
{
    "message_id": "integer",
    "user_id": "integer"
}
```

**成功响应**:
```json
{
    "success": true,
    "message": "Message recalled successfully"
}
```
**错误响应**:
```json
{
    "success": false,
    "message": "You can only recall your own messages"
}
```


---

## 使用说明
1. 所有时间字段使用 ISO 8601 格式（如 `"2023-10-05T14:30:00Z"`）
2. 用户操作约束：
   - 用户名必须唯一
   - 只能撤回自己发送的消息
3. 生产环境建议：
   - 启用 HTTPS
   - 使用 JWT 替代简单 Token
   - 添加请求速率限制