添加 API.md

api文档...?
2025-05-31 18:37:14 +08:00 · 2025-05-31 18:37:14 +08:00 · 01a2a6c53d
commit 01a2a6c53d
parent ddb9433d0b
1 changed files with 164 additions and 0 deletions
--- a/API.md
+++ b/API.md
@ -0,0 +1,164 @@
+# 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
+   - 添加请求速率限制