iTing API Documentation

本文档涵盖 iTing 后端服务的所有主要 API，适用于移动端、Web、第三方集成等场景。所有受保护接口需在 Header 中携带 JWT Token。

系统接口

健康检查

GET /api/health

curl -X GET http://localhost:3000/api/health

系统监控

GET /metrics

curl -X GET http://localhost:3000/metrics

认证与用户接口

Apple 登录/注册

POST /api/users/register

curl -X POST http://localhost:3000/api/users/register \
    -H "Content-Type: application/json" \
    -d '{
        "userIdentifier": "apple_user_id",
        "email": "user@example.com",
        "fullName": "张三",
        "deviceToken": "device_token_here"
    }'

用户登录

POST /api/users/login

curl -X POST http://localhost:3000/api/users/login \
    -H "Content-Type: application/json" \
    -d '{
        "email": "user@example.com",
        "password": "password"
    }'

获取/更新用户信息

GET /api/users/:userId/profile
PUT /api/users/:userId/profile

curl -X GET http://localhost:3000/api/users/user_id_here/profile \
    -H "Authorization: Bearer your-jwt-token"
curl -X PUT http://localhost:3000/api/users/user_id_here/profile \
    -H "Authorization: Bearer your-jwt-token" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "张三",
        "avatarUrl": "https://example.com/avatar.jpg"
    }'

设备管理接口

注册设备

POST /api/devices/device-info

curl -X POST http://localhost:3000/api/devices/device-info \
    -H "Authorization: Bearer your-jwt-token" \
    -H "Content-Type: application/json" \
    -d '{
        "deviceToken": "device_token_here",
        "deviceName": "iPhone 12",
        "systemVersion": "17.0",
        "userIdentifier": "user_id_here",
        "timestamp": "2025-07-11T12:00:00Z"
    }'

更新 DeviceToken

PUT /api/devices/token

curl -X PUT http://localhost:3000/api/devices/token \
    -H "Authorization: Bearer your-jwt-token" \
    -H "Content-Type: application/json" \
    -d '{
        "deviceToken": "new_device_token_here"
    }'

删除设备

DELETE /api/users/:userId/devices/:deviceToken

curl -X DELETE http://localhost:3000/api/users/user_id_here/devices/device_token_here \
    -H "Authorization: Bearer your-jwt-token"

主题订阅接口

获取所有主题

GET /api/topics

curl -X GET http://localhost:3000/api/topics \
    -H "Authorization: Bearer your-jwt-token"

订阅主题

POST /api/topics/subscribe

curl -X POST http://localhost:3000/api/topics/subscribe \
    -H "Authorization: Bearer your-jwt-token" \
    -H "Content-Type: application/json" \
    -d '{
        "user_id": "user_id_here",
        "topic_id": "topic_id_here",
        "sound_name": "default"
    }'

取消订阅

DELETE /api/topics/unsubscribe

curl -X DELETE http://localhost:3000/api/topics/unsubscribe \
    -H "Authorization: Bearer your-jwt-token" \
    -H "Content-Type: application/json" \
    -d '{
        "user_id": "user_id_here",
        "topic_id": "topic_id_here"
    }'

获取用户订阅

GET /api/topics/user/:userId

curl -X GET http://localhost:3000/api/topics/user/user_id_here \
    -H "Authorization: Bearer your-jwt-token"

消息中心接口

发送消息

POST /api/messages

curl -X POST http://localhost:3000/api/messages \
    -H "Authorization: Bearer your-jwt-token" \
    -H "Content-Type: application/json" \
    -d '{
        "content": "Hello, World!",
        "recipient_id": "recipient_id_here"
    }'

获取消息历史

GET /api/messages/history/:userId

curl -X GET http://localhost:3000/api/messages/history/user_id_here \
    -H "Authorization: Bearer your-jwt-token"

删除消息

DELETE /api/messages/:messageId

curl -X DELETE http://localhost:3000/api/messages/message_id_here \
    -H "Authorization: Bearer your-jwt-token"

偏好设置接口

获取用户偏好

GET /api/preferences/:userId

curl -X GET http://localhost:3000/api/preferences/user_id_here \
    -H "Authorization: Bearer your-jwt-token"

更新用户偏好

PUT /api/preferences/:userId

curl -X PUT http://localhost:3000/api/preferences/user_id_here \
    -H "Authorization: Bearer your-jwt-token" \
    -H "Content-Type: application/json" \
    -d '{
        "notification_sound": "default",
        "language": "zh-CN",
        "theme": "light"
    }'

通知设置与测试接口

获取通知设置

GET /api/notifications/settings/:userId

curl -X GET http://localhost:3000/api/notifications/settings/user_id_here \
    -H "Authorization: Bearer your-jwt-token"

更新通知设置

PUT /api/notifications/settings/:userId

curl -X PUT http://localhost:3000/api/notifications/settings/user_id_here \
    -H "Authorization: Bearer your-jwt-token" \
    -H "Content-Type: application/json" \
    -d '{
        "enabled": true,
        "sound_enabled": true,
        "vibration_enabled": true
    }'

发送测试通知

POST /api/notifications/test

curl -X POST http://localhost:3000/api/notifications/test \
    -H "Authorization: Bearer your-jwt-token" \
    -H "Content-Type: application/json" \
    -d '{
        "device_token": "device_token_here"
    }'

通用返回格式与错误码

返回格式

{
    "status": "success", // 或 "error"
    "data": { ... },      // 具体数据内容
    "message": "操作成功/失败原因"
}

常见错误码

  • 401 未认证（JWT Token 无效或缺失）
  • 403 无权限
  • 404 资源不存在
  • 409 冲突（如注册用户已存在）
  • 429 请求过于频繁
  • 500 服务器内部错误