KnowHealth

KnowHealth API文档

概述

本文档描述了KnowHealth项目的API接口规范和使用方法。

快速开始

基础URL

http://localhost:8000/api/v1

认证方式

所有API请求需要在请求头中包含JWT令牌：

Authorization: Bearer <your-jwt-token>

获取令牌

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "your-username", "password": "your-password"}'

API接口

基础接口

健康检查

GET /health

响应示例：

{
  "status": "healthy",
  "service": "KnowHealth",
  "version": "1.0.0"
}

系统状态

GET /api/v1/status

响应示例：

{
  "status": "operational",
  "uptime": "99.9%",
  "response_time": "45ms"
}

数据接口

获取数据列表

GET /api/v1/data

查询参数：

响应示例：

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5
  }
}

上传数据

POST /api/v1/data
Content-Type: multipart/form-data

请求体：

获取特定数据

GET /api/v1/data/{id}

分析接口

数据分析

POST /api/v1/analyze
Content-Type: application/json

请求体：

{
  "dataset": "dataset_name",
  "variables": ["var1", "var2"],
  "analysis_type": "statistical",
  "parameters": {
    "method": "regression",
    "confidence_level": 0.95
  }
}

响应示例：

{
  "analysis_id": "analysis_001",
  "summary": {
    "dataset": "dataset_name",
    "variables": ["var1", "var2"]
  },
  "statistics": {
    "mean": 0.5,
    "std": 0.1,
    "p_value": 0.05
  },
  "visualizations": ["histogram.png", "scatter_plot.png"],
  "conclusions": ["数据呈正态分布", "变量间存在显著相关性"]
}

用户接口

用户登录

POST /api/v1/auth/login
Content-Type: application/json

请求体：

{
  "username": "your-username",
  "password": "your-password"
}

响应示例：

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

用户注册

POST /api/v1/auth/register
Content-Type: application/json

请求体：

{
  "username": "new-username",
  "email": "user@example.com",
  "password": "secure-password",
  "full_name": "用户姓名"
}

错误处理

错误响应格式

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "请求参数无效",
    "details": {
      "field": "email",
      "reason": "邮箱格式不正确"
    }
  }
}

常见错误码

SDK和工具

Python SDK

import requests

class KnowhealthClient:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.headers = {"Authorization": f"Bearer {token}"}
    
    def get_data(self, page=1, limit=20):
        response = requests.get(
            f"{self.base_url}/api/v1/data",
            params={"page": page, "limit": limit},
            headers=self.headers
        )
        return response.json()
    
    def analyze(self, dataset, variables, analysis_type):
        response = requests.post(
            f"{self.base_url}/api/v1/analyze",
            json={
                "dataset": dataset,
                "variables": variables,
                "analysis_type": analysis_type
            },
            headers=self.headers
        )
        return response.json()

使用示例

# 初始化客户端
client = KnowhealthClient(
    base_url="http://localhost:8000",
    token="your-jwt-token"
)

# 获取数据
data = client.get_data(page=1, limit=10)
print(data)

# 分析数据
analysis = client.analyze(
    dataset="my_dataset",
    variables=["var1", "var2"],
    analysis_type="statistical"
)
print(analysis)

部署说明

开发环境

# 克隆仓库
git clone https://github.com/MoKangMedical/KnowHealth.git
cd KnowHealth

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑.env文件

# 启动服务
python -m uvicorn src.main:app --reload

生产环境

# 使用Docker Compose
docker-compose up -d

# 或手动部署
# 参考部署文档

监控和日志

监控端点

日志配置

import logging

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('/var/log/KnowHealth/app.log'),
        logging.StreamHandler()
    ]
)

常见问题

Q: 如何重置密码？

A: 访问 /api/v1/auth/reset-password 接口，提供邮箱地址。

Q: 如何申请API密钥？

A: 登录后访问 /api/v1/settings/api-keys 生成新的API密钥。

Q: 请求频率限制是多少？

A: 默认限制为每分钟100次请求，可通过配置文件调整。

联系方式

更新日志

请查看 CHANGELOG.md 获取最新更新信息。

This site is open source. Improve this page.