Chapter 05: Phase 2 — API Interface

5.1 Phase 2 in one paragraph

Phase 2 specifies the HTTPS surface that a wearable health host (typically a vendor cloud, a clinical RPM platform, or a hospital bridge) exposes for the data families defined in Phase 1. Transport is TLS 1.3 (IETF RFC 8446) only; HTTP/2 RECOMMENDED. The surface follows REST conventions with cursor-based pagination and Server-Sent Events for measurement streams.

5.2 Discovery

Every host publishes a discovery document at /.well-known/wia-wearable-health listing endpoints, supported signatures, supported measurement types, and rate limits. Discovery responses are cacheable for 300 seconds.

5.3 Device endpoints

PUT    /wh/device/{device_id}         (signed)
GET    /wh/device/{device_id}
GET    /wh/device?patient_id={id}
DELETE /wh/device/{device_id}         (signed; tombstone)

5.4 Sync endpoint (bulk upload)

The sync endpoint accepts a bulk packet typical of periodic device sync operations. It honours Idempotency-Key per IETF draft idempotency-key-header so the device can safely retry on flaky network conditions.

POST /wh/sync
Content-Type: application/json
Idempotency-Key: 7e3a9b6c-...
Authorization: WIA-Sig keyid="...",signature="..."

5.5 Measurement query and stream

GET /wh/measurement/{measurement_id}
GET /wh/measurement?patient_id={id}&type={t}&from={ts}&to={ts}
GET /wh/measurement/stream/{device_id}    (Server-Sent Events)

The stream variant is the primary path for live clinical dashboards. Reconnecting clients pass Last-Event-Id per WHATWG HTML §9.2 to recover missed events.

5.6 Session, alert, calibration endpoints

The remaining endpoint families follow the same shape: POST/GET/PATCH on /wh/{family}/{id}. PATCH on a session is permitted only within 24 hours of session end (for summary updates from late-arriving measurements). PATCH on a calibration is forbidden — corrections are appended as a new calibration referencing the prior via previous_calibration_id.

5.7 Authentication and errors

Writes require HTTP Message Signatures per IETF RFC 9421. Reads MAY be anonymous subject to the discovery rate limit; PHI-bearing reads MUST be authenticated. Errors follow IETF RFC 9457 problem details with type URIs under https://wiastandards.com/wearable-health/errors/.

5.8 Operational recommendations

• Hosts MUST persist incoming writes durably before acknowledging.
• Hosts SHOULD provide a separate read-replica endpoint for high-rate measurement queries.
• Hosts SHOULD expose a /wh/health liveness probe outside the public rate-limit accounting.
• Hosts SHOULD retain problem-detail responses to identified peers for 30 days for cross-host debugging.

Chapter Cross-References

This chapter participates in the WIA-MED-020 8-chapter survey. Each chapter is intended to be readable standalone, but together they map the full surface of the standard. The Phase numbering used throughout (Phase 1 / 2 / 3 / 4) refers to the four-document specification — Chapter 4 covers Phase 1, Chapter 5 covers Phase 2, Chapter 6 covers Phase 3, Chapter 7 covers Phase 4.

Where to look next

• Conformance test suite — https://github.com/WIA-Official/wia-wearable-health-conformance is the single source of truth. When this book and the test suite disagree, the test suite wins.
• Reference container — wia/wearable-health-host:1.0.0 implements every Phase 2 endpoint with mock data; integrators exercise their bridge against it before going to production.
• Companion CLI — cli/wearable-health.sh ships sample envelope generators (validate, device, measurement, alert, consent, info subcommands) so an implementer can produce conformant payloads without hand-rolling JSON.
• Companion standards — WIA-OMNI-API for credentials, WIA-AIR-SHIELD for transport hardening, WIA-INTENT for clinician intent lowering, WIA-ACCESSIBILITY for accommodations, WIA Vital Sign Streaming for high-rate continuous waveforms.

Patient-First Design

Every choice in this standard is filtered through the question: "does this make wearable data more useful for the patient and their care team, or just easier for vendors to ship?" When the two conflict, the patient and care team win. That is why the standard mandates explicit patient consent for cross-host data flow, refuses to accept clinical-grade claims without regulatory clearance, and requires implementations to surface calibration provenance so that clinicians can verify the source quality of every measurement they make decisions on.