> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://blueprint.ziro.health/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://blueprint.ziro.health/_mcp/server.

# API Design & FHIR Interoperability

FHIR (Fast Healthcare Interoperability Resources) is the modern standard for health data exchange. Designing FHIR-native APIs from the start enables seamless integration with EHRs, health information exchanges, and other health IT systems.

## FHIR R4 Basics

FHIR organizes health data into resources:

| Resource          | Purpose                      | Example Use              |
| ----------------- | ---------------------------- | ------------------------ |
| Patient           | Demographics, identifiers    | Patient registration     |
| Observation       | Measured value               | Blood pressure reading   |
| Condition         | Diagnosed problem            | Type 2 diabetes          |
| MedicationRequest | Prescribed medication        | Metformin 500mg          |
| Encounter         | Patient-provider interaction | Office visit             |
| CarePlan          | Planned care                 | Diabetes management plan |

## RESTful FHIR API Patterns

```
GET  /Patient/{id}                    — Read patient
POST /Patient                         — Create patient
GET  /Patient/{id}/Observation        — Search observations
POST /Observation/$lastn              — Get most recent values
GET  /Patient/{id}/$everything        — Get all patient data (bulk)
```

## SMART-on-FHIR for EHR Integration

SMART-on-FHIR enables your app to launch from within an EHR:

* **Launch flow**: Provider launches your app from within the EHR
* **Authorization**: OAuth 2.0 with patient/provider context
* **Data access**: Your app receives a FHIR base URL + access token
* **Scopes**: Granular permissions per resource type and operation
* **Standalone launch**: Patient can authorize app access independently

## Authentication and Authorization

Health API security patterns:

* **OAuth 2.0**: Industry standard for delegated authorization
* **SMART Backend Services**: Machine-to-machine auth for bulk data access
* **JWT validation**: Use JWKS endpoints for token verification
* **Rate limiting**: Implement per-client rate limits appropriate for health data volume
* **Audit logging**: Log every API access with user, resource, action, and timestamp

## API Versioning

Health APIs evolve with clinical guidelines:

* **URL versioning**: `/v1/Patient`, `/v2/Patient`
* **FHIR versioning**: FHIR R4, R5 — maintain backward compatibility
* **Deprecation policy**: Minimum 12-month deprecation notice
* **Migration guides**: Document breaking changes with migration paths