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:

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