Chapter 5: Phase 2 - API Interface

RESTful APIs for Traditional Medicine Integration

5.1 API Design Principles

The WIA-TRADITIONAL-MEDICINE API follows modern RESTful design principles:

Resource-Oriented: Clear resource hierarchies (patients, diagnoses, herbs, formulas)
Stateless: Each request contains all necessary information
Versioned: API versioning in URL path (v1, v2)
Documented: OpenAPI 3.0 specification available
Secure: OAuth 2.0 authentication, HTTPS required

5.2 Core API Endpoints

Constitution Assessment

POST /api/v1/constitution/assess

Submit questionnaire responses and receive constitution analysis

// Request
POST /api/v1/constitution/assess
Content-Type: application/json

{
  "patient_id": "PAT-2025-001",
  "system": "tcm",
  "questionnaire_type": "CCMQ",
  "responses": {
    "q1": 4, "q2": 3, "q3": 5, ...
  },
  "include_recommendations": true
}

// Response
{
  "profile_id": "PROF-2025-12345",
  "primary_constitution": "phlegm_dampness",
  "secondary_constitutions": ["qi_deficiency"],
  "scores": {
    "phlegm_dampness": 0.72,
    "qi_deficiency": 0.45,
    ...
  },
  "confidence": 0.85,
  "recommendations": {
    "diet": [...],
    "lifestyle": [...],
    "herbs_to_consider": [...]
  }
}

GET /api/v1/constitution/profile/{patient_id}

Retrieve stored constitution profile for a patient

Traditional Diagnosis

POST /api/v1/diagnosis/traditional

Record a traditional diagnosis with Four Examinations data

POST /api/v1/diagnosis/tongue/analyze

Submit tongue image for AI analysis

// Request
POST /api/v1/diagnosis/tongue/analyze
Content-Type: multipart/form-data

image: [tongue_photo.jpg]
patient_id: PAT-2025-001

// Response
{
  "analysis_id": "TONG-2025-789",
  "findings": {
    "body_color": "pale",
    "body_shape": "teeth_marked",
    "coating": {
      "color": "white",
      "thickness": "thick",
      "distribution": "root_thicker"
    },
    "moisture": "wet"
  },
  "patterns_suggested": [
    {
      "pattern": "spleen_qi_deficiency",
      "confidence": 0.89
    },
    {
      "pattern": "dampness",
      "confidence": 0.82
    }
  ],
  "icd11_tm_codes": ["TM1:SF32.2"]
}

Herbal Medicine

GET /api/v1/herbs/search

Search herbal medicine database by name, property, or indication

POST /api/v1/herbs/formula/recommend

Get formula recommendations based on pattern diagnosis

// Request
POST /api/v1/herbs/formula/recommend
{
  "pattern": "spleen_qi_deficiency_with_dampness",
  "constitution": "phlegm_dampness",
  "current_medications": ["Metformin"],
  "allergies": [],
  "pregnancy_status": false
}

// Response
{
  "recommendations": [
    {
      "formula": {
        "name_zh": "六君子湯",
        "name_pinyin": "Liu Jun Zi Tang",
        "name_en": "Six Gentlemen Decoction"
      },
      "match_score": 0.92,
      "composition": [
        {"herb": "人參", "dose_g": 9},
        {"herb": "白朮", "dose_g": 9},
        {"herb": "茯苓", "dose_g": 9},
        {"herb": "炙甘草", "dose_g": 6},
        {"herb": "陳皮", "dose_g": 6},
        {"herb": "半夏", "dose_g": 6}
      ],
      "safety_check": {
        "status": "safe",
        "interactions": [],
        "warnings": []
      }
    }
  ]
}

Drug Interaction Checking

POST /api/v1/herbs/interactions

Check for herb-drug and herb-herb interactions

// Request
POST /api/v1/herbs/interactions
{
  "herbs": ["人參", "當歸", "川芎"],
  "medications": ["Warfarin", "Aspirin"]
}

// Response
{
  "interactions": [
    {
      "type": "herb_drug",
      "herb": "當歸",
      "drug": "Warfarin",
      "severity": "major",
      "effect": "May enhance anticoagulant effect",
      "mechanism": "Coumarin compounds inhibit vitamin K metabolism",
      "recommendation": "Monitor INR closely or avoid combination",
      "references": ["PMID: 12345678"]
    }
  ],
  "overall_risk": "high",
  "recommendations": [
    "Consider alternative herbs with lower bleeding risk",
    "If combination necessary, monitor INR weekly"
  ]
}

5.3 Streaming and Real-time APIs

For applications requiring real-time data, WebSocket endpoints are available:

ws://api-wialive.smilestory.ai/v1/pulse/stream - Real-time pulse sensor data
ws://api-wialive.smilestory.ai/v1/monitoring/session - Treatment session monitoring

5.4 Authentication and Rate Limiting

            Security Requirements:
            OAuth 2.0 Bearer tokens required for all endpoints
API keys for server-to-server communication
Rate limits: 1000 requests/hour for standard tier
All patient data encrypted at rest and in transit
HIPAA/GDPR compliant data handling

        

5.5 SDK Support

Official SDKs are available for:

TypeScript/JavaScript: @wia/traditional-medicine-sdk
Python: wia-traditional-medicine
Java: com.wia.traditional-medicine
Swift: WIATraditionalMedicine