Tab-Specific API Requirements for Frontend Integration

Overview

This document outlines the specific API requirements for each tab in the CMS careplan patient interface at /cms/careplan/patient/{patientId}/{appointmentId}. Based on the frontend implementation analysis, each tab has specific data fetching and update patterns.

Frontend Tab Structure

Based on the frontend analysis, the tabs are:

Vitals → /appointments/{appointment_id}/clinical_observations/vitals
Observations → /appointments/{appointment_id}/clinical_impressions
Medications → /appointments/{appointment_id}/medication_requests
Investigations → /appointments/{appointment_id}/service_requests
Advice → /appointments/{appointment_id}/care_plan/advice
Next Visit → /appointments/{appointment_id}/care_plan/follow_up

Tab-Specific API Requirements

1. Vitals Tab

Frontend Component: VitalsTab.tsx Current Data Flow: Auto-save with 2-5 second debounce

Required APIs

GET /appointments/{appointment_id}/clinical_observations/vitals

{
  "appointment_id": "appt-001",
  "patient_id": "pat-001", 
  "vital_signs": {
    "blood_pressure": {
      "systolic": 120,
      "diastolic": 80,
      "unit": "mmHg",
      "measured_at": "2025-09-10T10:30:00Z"
    },
    "heart_rate": {
      "value": 72,
      "unit": "bpm", 
      "measured_at": "2025-09-10T10:30:00Z"
    },
    "temperature": {
      "value": 98.6,
      "unit": "°F",
      "measured_at": "2025-09-10T10:30:00Z"
    },
    "respiratory_rate": {
      "value": 16,
      "unit": "breaths/min",
      "measured_at": "2025-09-10T10:30:00Z"
    },
    "oxygen_saturation": {
      "value": 98,
      "unit": "%",
      "measured_at": "2025-09-10T10:30:00Z"
    },
    "weight": {
      "value": 70,
      "unit": "kg",
      "measured_at": "2025-09-10T10:30:00Z"
    },
    "height": {
      "value": 175,
      "unit": "cm",
      "measured_at": "2025-09-10T10:30:00Z"
    },
    "bmi": {
      "value": 22.9,
      "unit": "kg/m²",
      "calculated_at": "2025-09-10T10:30:00Z"
    }
  },
  "normal_ranges": {
    "blood_pressure": {"systolic": [90, 140], "diastolic": [60, 90]},
    "heart_rate": [60, 100],
    "temperature": [97.0, 99.5],
    "respiratory_rate": [12, 20],
    "oxygen_saturation": [95, 100]
  }
}

PUT /appointments/{appointment_id}/clinical_observations/vitals

{
  "vital_signs": {
    // Same structure as GET response
  }
}

2. Observations Tab

Frontend Component: ObservationsTab.tsx Current Data Flow: Real-time updates with AI scribe integration

Required APIs

GET /appointments/{appointment_id}/clinical_impressions

{
  "appointment_id": "appt-001",
  "patient_id": "pat-001",
  "clinical_assessment": {
    "chief_complaint": "Chest pain for 2 hours",
    "history_present_illness": "Patient reports sharp chest pain started 2 hours ago...",
    "past_medical_history": "Hypertension, controlled on medication",
    "family_history": "Father had MI at age 60",
    "social_history": "Non-smoker, occasional alcohol use",
    "allergies": ["Penicillin", "Shellfish"]
  },
  "physical_examination": {
    "general_appearance": "Well-appearing, no acute distress",
    "vital_signs_summary": "Stable",
    "cardiovascular": "Regular rate and rhythm, no murmurs",
    "respiratory": "Clear to auscultation bilaterally", 
    "abdominal": "Soft, non-tender",
    "neurological": "Alert and oriented x3",
    "skin": "Warm, dry, no rashes"
  },
  "assessment": {
    "provisional_diagnosis": ["Chest pain, likely muscular"],
    "differential_diagnosis": ["Costochondritis", "Muscle strain", "GERD"],
    "clinical_impression": "Low risk for cardiac etiology based on history and examination",
    "icd_codes": ["R06.02", "M79.1"]
  },
  "plan": {
    "immediate_management": "Pain management, observation",
    "follow_up_instructions": "Return if symptoms worsen",
    "patient_education": "Discussed signs of cardiac emergency"
  },
  "ai_suggestions": {
    "enabled": true,
    "suggestions": [
      {
        "type": "diagnosis",
        "confidence": 0.85,
        "suggestion": "Consider ECG to rule out cardiac causes"
      }
    ]
  }
}

PUT /appointments/{appointment_id}/clinical_impressions

{
  "clinical_assessment": { /* same structure */ },
  "physical_examination": { /* same structure */ },
  "assessment": { /* same structure */ },
  "plan": { /* same structure */ }
}

3. Medications Tab

Frontend Component: MedicationsTab.tsx Current Data Flow: Drug search, interaction checking, e-prescription sending

Required APIs

GET /appointments/{appointment_id}/medication_requests

{
  "appointment_id": "appt-001", 
  "patient_id": "pat-001",
  "active_medications": [
    {
      "id": "med-001",
      "medication_name": "Lisinopril",
      "strength": "10mg",
      "form": "Tablet",
      "dosage_instruction": "Take 1 tablet by mouth once daily",
      "frequency": "once daily",
      "quantity": 30,
      "duration": "30 days",
      "instructions": "Take with food",
      "prescriber": "Dr. Smith",
      "prescribed_date": "2025-09-10",
      "status": "active",
      "refills": 5
    }
  ],
  "current_prescription_medications": [
    {
      "id": "med-002",
      "medication_name": "Ibuprofen", 
      "strength": "400mg",
      "form": "Tablet",
      "dosage_instruction": "Take 1 tablet by mouth every 6 hours as needed for pain",
      "frequency": "q6h PRN",
      "quantity": 20,
      "duration": "7 days", 
      "instructions": "Take with food, do not exceed 4 doses per day",
      "status": "new"
    }
  ],
  "drug_interactions": [
    {
      "medications": ["Lisinopril", "Ibuprofen"],
      "severity": "moderate",
      "description": "NSAIDs may reduce the effectiveness of ACE inhibitors"
    }
  ],
  "allergies": ["Penicillin", "Shellfish"]
}

POST /appointments/{appointment_id}/medication_requests

{
  "medication": {
    "medication_name": "Ibuprofen",
    "strength": "400mg", 
    "form": "Tablet",
    "dosage_instruction": "Take 1 tablet by mouth every 6 hours as needed for pain",
    "frequency": "q6h PRN",
    "quantity": 20,
    "duration": "7 days",
    "instructions": "Take with food"
  }
}

GET /medications?search={searchTerm}

{
  "results": [
    {
      "name": "Ibuprofen",
      "strengths": ["200mg", "400mg", "600mg"],
      "forms": ["Tablet", "Capsule", "Liquid"], 
      "generic_name": "Ibuprofen",
      "brand_names": ["Advil", "Motrin"],
      "category": "NSAID"
    }
  ]
}

4. Investigations Tab

Frontend Component: InvestigationsTab.tsx Current Data Flow: Test ordering, result tracking, urgency management

Required APIs

GET /appointments/{appointment_id}/service_requests

{
  "appointment_id": "appt-001",
  "patient_id": "pat-001", 
  "ordered_tests": [
    {
      "id": "test-001",
      "service_name": "Complete Blood Count",
      "service_type": "lab_test",
      "category": "Hematology",
      "status": "ordered",
      "urgency": "routine",
      "ordered_date": "2025-09-10",
      "expected_date": "2025-09-11",
      "clinical_notes": "Check for anemia",
      "lab_reference": "LAB-12345"
    }
  ],
  "completed_tests": [
    {
      "id": "test-002", 
      "service_name": "Basic Metabolic Panel",
      "service_type": "lab_test",
      "category": "Chemistry",
      "status": "completed",
      "completed_date": "2025-09-09",
      "results": {
        "glucose": {"value": 95, "unit": "mg/dL", "reference_range": "70-100"},
        "creatinine": {"value": 1.0, "unit": "mg/dL", "reference_range": "0.6-1.3"}
      }
    }
  ],
  "imaging_studies": [
    {
      "id": "img-001",
      "service_name": "Chest X-Ray",
      "service_type": "imaging", 
      "category": "Radiology",
      "status": "completed",
      "completed_date": "2025-09-08",
      "findings": "Normal chest radiograph",
      "report_url": "/reports/img-001.pdf"
    }
  ]
}

POST /appointments/{appointment_id}/service_requests

{
  "service": {
    "service_name": "Complete Blood Count",
    "service_type": "lab_test", 
    "category": "Hematology",
    "urgency": "routine",
    "clinical_notes": "Check for anemia"
  }
}

GET /investigations?category={category}&search={searchTerm}

{
  "results": [
    {
      "name": "Complete Blood Count",
      "code": "CBC",
      "category": "Hematology",
      "type": "lab_test",
      "description": "Evaluates blood cells and overall health"
    }
  ]
}

5. Advice Tab

Frontend Component: AdviceTab.tsx Current Data Flow: Template-based advice, patient instruction management

Required APIs

GET /appointments/{appointment_id}/care_plan/advice

{
  "appointment_id": "appt-001",
  "patient_id": "pat-001",
  "advice_categories": {
    "medications": {
      "instructions": [
        "Take all medications as prescribed",
        "Do not stop medications without consulting your doctor"
      ]
    },
    "diet": {
      "instructions": [
        "Follow low-sodium diet",
        "Limit alcohol consumption to 1 drink per day"
      ]
    },
    "activity": {
      "instructions": [
        "Light exercise as tolerated", 
        "Avoid heavy lifting for 1 week"
      ]
    },
    "follow_up": {
      "instructions": [
        "Return in 2 weeks for follow-up",
        "Call if symptoms worsen"
      ]
    },
    "warning_signs": {
      "instructions": [
        "Return immediately if chest pain worsens",
        "Seek emergency care for shortness of breath"
      ]
    }
  },
  "custom_advice": [
    "Monitor blood pressure daily and keep a log",
    "Schedule appointment with cardiologist within 1 month"
  ],
  "patient_education_materials": [
    {
      "title": "Managing Hypertension",
      "url": "/education/hypertension.pdf",
      "type": "pdf"
    }
  ]
}

PUT /appointments/{appointment_id}/care_plan/advice

{
  "advice_categories": { /* same structure */ },
  "custom_advice": [ /* array of strings */ ]
}

6. Next Visit Tab

Frontend Component: Part of AdviceTab.tsx or separate component Current Data Flow: Follow-up scheduling, appointment booking

Required APIs

GET /appointments/{appointment_id}/care_plan/follow_up

{
  "appointment_id": "appt-001",
  "patient_id": "pat-001",
  "follow_up_plan": {
    "recommended_interval": "2 weeks",
    "follow_up_type": "routine",
    "priority": "standard",
    "specific_concerns": [
      "Monitor medication effectiveness",
      "Check blood pressure control"
    ]
  },
  "scheduled_appointments": [
    {
      "appointment_id": "appt-001",
      "scheduled_date": "2025-09-24T10:00:00Z",
      "appointment_type": "follow-up",
      "provider": "Dr. Smith",
      "status": "scheduled"
    }
  ],
  "available_slots": [
    {
      "date": "2025-09-24",
      "time_slots": ["09:00", "10:00", "11:00", "14:00", "15:00"]
    },
    {
      "date": "2025-09-25", 
      "time_slots": ["09:30", "10:30", "13:30", "14:30"]
    }
  ]
}

POST /appointments/{appointment_id}/care_plan/follow_up

{
  "follow_up": {
    "scheduled_date": "2025-09-24T10:00:00Z",
    "appointment_type": "follow-up",
    "duration": 30,
    "notes": "Follow-up for chest pain evaluation"
  }
}

Common API Patterns

Authentication & Authorization

All APIs require clinic-based authentication:

Authorization: Bearer <token>
X-Clinic-Id: <clinic_id>

Error Responses

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Invalid medication dosage",
    "details": {"field": "dosage", "issue": "must be positive"}
  }
}

Auto-Save Pattern

Frontend implements auto-save with debounce. APIs should support partial updates:

PUT /api/{resource}/{id}
Content-Type: application/json

{
  "field_to_update": "new_value"
  // Only changed fields included
}

Real-Time Updates

Some tabs may benefit from real-time updates via Ably (especially for AI suggestions):

// Ably channel subscription
const channel = ably.channels.get(`appointment:${appointmentId}`);

// Subscribe to AI suggestions
channel.subscribe('ai_suggestion', (message) => {
  // message.data = {type: "diagnosis_suggestion", confidence: 0.85, suggestion: "..."}
  handleAISuggestion(message.data);
});

// Subscribe to medication interactions
channel.subscribe('drug_interaction', (message) => {
  // message.data = {medications: ["Drug A", "Drug B"], severity: "moderate", description: "..."}
  showInteractionWarning(message.data);
});

Implementation Priority

High Priority: Medications, Observations (core clinical functionality)
Medium Priority: Vitals, Investigations (important but existing patterns)
Low Priority: Advice, Next Visit (enhancement features)

Notes

All datetime fields should be ISO 8601 format with timezone
All APIs should support snake_case JSON as per project conventions
Consider implementing GraphQL for complex data fetching if REST becomes unwieldy
Ensure all medical data changes are logged for audit trails
FHIR resource IDs should be meaningful for debugging (not random UUIDs)

Tab-Specific API Requirements for Frontend Integration

OverviewCopy Anchor Link

Frontend Tab StructureCopy Anchor Link

Tab-Specific API RequirementsCopy Anchor Link

1. Vitals TabCopy Anchor Link

Required APIsCopy Anchor Link

2. Observations TabCopy Anchor Link

Required APIsCopy Anchor Link

3. Medications TabCopy Anchor Link

Required APIsCopy Anchor Link

4. Investigations TabCopy Anchor Link

Required APIsCopy Anchor Link

5. Advice TabCopy Anchor Link

Required APIsCopy Anchor Link

6. Next Visit TabCopy Anchor Link

Required APIsCopy Anchor Link

Common API PatternsCopy Anchor Link

Authentication & AuthorizationCopy Anchor Link

Error ResponsesCopy Anchor Link

Auto-Save PatternCopy Anchor Link

Real-Time UpdatesCopy Anchor Link

Implementation PriorityCopy Anchor Link

NotesCopy Anchor Link

On this page

Overview

Frontend Tab Structure

Tab-Specific API Requirements

1. Vitals Tab

Required APIs

2. Observations Tab

Required APIs

3. Medications Tab

Required APIs

4. Investigations Tab

Required APIs

5. Advice Tab

Required APIs

6. Next Visit Tab

Required APIs

Common API Patterns

Authentication & Authorization

Error Responses

Auto-Save Pattern

Real-Time Updates

Implementation Priority

Notes