MED-API

Overview

MED-API is the backend service of the MEDWEAR platform. It provides a secure REST API for ingesting, querying, and managing wearable health data, deployed alongside MinIO, InfluxDB, PostgreSQL, Keycloak, Dagster, Grafana, and pgAdmin as a single-server stack.

For installation, Docker setup, authentication, and testing, see the MED-API Setup section in Documentation. Full documentation is also available on Google Drive.

Roles

Web Interface

Available at https://localhost. Login with Keycloak credentials.

Data Ingestion

POST /v1/data/batch - Structured sensor data

Stores metadata in PostgreSQL and signals in InfluxDB. Supports JSON and CSV.

Supported signal types: ECG, BCG, PPG, IMU, EEG, EDA, HR, HRV

curl -k -X POST https://localhost/v1/data/batch \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "batches": [{
      "header": {
        "uuid": "your-uuid",
        "schema_id": "ecg-lead-1.x",
        "source_creation_date_time": "2026-03-12T10:00:00Z",
        "acquisition_rate": {"value": 250.0, "unit": "Hz", "number_of_times": 1}
      },
      "body": {
        "ecg_lead_data": [0.12, 0.15, 0.11],
        "unit": "mV",
        "effective_time_frame": {"time_interval": {
          "start_date_time": "2026-03-12T10:00:00Z",
          "end_date_time": "2026-03-12T10:00:03Z"
        }}
      },
      "signal_type": "ECG",
      "patient_id": 123456,
      "device_id": "polar-h10-01",
      "idempotency_key": "polar-h10-01-20260312-001"
    }]
  }'

POST /v1/data/upload - Raw file upload

Stores raw files (.cwa, .json, .csv) in MinIO. Max 1 GB.

curl -k -X POST https://localhost/v1/data/upload \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/octet-stream" \
  -H "X-Filename: ecg_data.csv" \
  --data-binary @ecg_data.csv

Query Endpoints

Query parameters for /v1/data: patient_ids, signal_type, start, end, device_id, project_id, limit, offset, metadata_only, show_deleted, format (json/csv), downsample

Admin Endpoints

Error Responses

All API errors return a consistent JSON format:

{
  "detail": {
    "error": "UPPER_SNAKE_CODE",
    "detail": "Human-readable message",
    "timestamp": "2026-03-31T20:00:00Z"
  }
}

Rate Limiting

Multi-Project Architecture

Each project has its own PostgreSQL database (medwear_project1, medwear_project2, etc.).

• Tables per project: measurement_batch, audit_log, user_project, deleted_files
• Central postgres DB tracks soft-deleted projects in deleted_projects
• global_admin can create and delete projects via the Admin tab or API
• Grafana datasources are auto-provisioned for each project on startup and sync hourly

Soft Delete & Purge

All deletes are soft - data is marked deleted and permanently removed after 24 hours.

The purge loop runs every hour. Deleted items can be restored before the 24h window via the frontend or API.

Two-Factor Authentication (2FA)

Optional TOTP-based 2FA using any authenticator app (e.g. Google Authenticator).

GDPR / Privacy

MedWear implements GDPR compliance via /v1/data/gdpr/* endpoints. All write operations require project_admin or global_admin role.

ROS 2 Real-Time Bridge

Streams live biosignal data from ROS 2 topics directly into the MedWear API.

docker build -t medwear-ros2-bridge ./ros2_to_medwear

docker run --rm \
    --network host \
    -e MEDWEAR_USERNAME=<keycloak_user> \
    -e MEDWEAR_PASSWORD=<keycloak_password> \
    -e API_BASE_URL=https://<server-ip>/v1 \
    medwear-ros2-bridge \
    --config config.yaml \
    --device corsano-001 \
    --patient <patient_id> \
    --project <project_id>

Code Structure

medwear_med_api/
  medwear_med_api/
    routers/
      utils.py       - shared helpers
      batches.py     - batch query/delete/restore endpoints
      files.py       - MinIO file endpoints
      patients.py    - patient timeline endpoint
      admin.py       - user/project/activity management
      totp.py        - 2FA (TOTP) endpoints
    query_router.py
    batch_router.py  - data ingestion endpoints
    auth.py          - Keycloak JWT validation
    audit.py         - request audit logging middleware
    db.py            - per-project session factory
    models.py        - SQLModel table definitions
    grafana_utils.py - Grafana datasource auto-provisioning
    influx_reader.py - InfluxDB signal queries
    influx_writer.py - InfluxDB signal writes
  scripts/
    run_med_api.py
    test_phase3.py / test_phase4.py / test_phase5.py