Building a healthcare app on top of a FHIR API involves five practical considerations that go beyond "pick a client SDK." These shape both the initial implementation and ongoing maintenance.
**1. Auth model: SMART on FHIR launch.** Public apps use SMART patient launch; system integrations use SMART Backend Services. Choose based on what launches the app.
2. Scope selection. SMART v2 scopes are fine-grained (patient/Observation.rs). Request minimum scopes; expand only when justified.
3. Rate limit handling. EHRs enforce rate limits per token. Implement exponential backoff on 429 responses. Test at rate limits, not below.
4. Pagination via _include and link.next. Multi-page responses use link.next for pagination. Bundle-style pagination is server-side; clients follow links.
5. Terminology binding awareness. Coded values come with system + code + potentially outdated display. Use $lookup for current display.
SDK choice by language
| Language | Recommended SDK |
|---|---|
| JavaScript/TypeScript | fhirclient.js or Medplum SDK |
| Java | HAPI FHIR client |
| Python | fhir.resources |
| .NET | Firely SDK |
| Go | Samply Go FHIR |
Common integration failures
| Failure | Root cause | Fix |
|---|---|---|
| Silent 401 errors | Expired token, no refresh | Implement refresh flow |
| Rate limit responses | No backoff | Exponential backoff |
| Missing data | Wrong scopes | Request necessary scopes |
| Wrong display strings | Cached terminology | $lookup on render |
| Broken pagination | Manual URL construction | Follow link.next |
Testing considerations
1. Test against sandbox with production-like scopes. 2. Test error paths (401, 403, 429) explicitly. 3. Test with realistic terminology (not just test codes). 4. Test bulk data separately from REST.
FHIR API integration is well-understood in 2026. The five considerations above cover most production-ready apps.