What Is a FHIR API? — How FHIR APIs Work (REST, JSON, Endpoints, Search & Security)
A FHIR API is a web-based interface that exposes FHIR resources (Patient, Observation, Encounter, etc.) using HTTP methods (GET, POST, PUT, PATCH, DELETE) and standard formats (JSON or XML). FHIR APIs follow a predictable RESTful pattern, support rich search, versioning and metadata, and are commonly secured using OAuth2 / SMART on FHIR.
Core Concepts of FHIR API
| Concept | Short explanation |
|---|---|
| Resource endpoint | [base]/Patient, [base]/Observation, etc. — each resource type has a predictable URL. ( blog.hl7.org ) |
| Read/Write operations | Standard HTTP verbs perform CRUD operations on resources (GET, POST, PUT, PATCH, DELETE). blog.hl7.org |
| Formats | JSON (preferred) and XML serializations. |
| Search interaction | Powerful query syntax using search parameters and modifiers (e.g., ?patient=123&code=xyz). ( HL7 ) |
| Security | OAuth2/OpenID Connect patterns; SMART on FHIR provides app launch and context flows. ( hdocs.smarthealthit.org ) |
Typical FHIR REST Interactions
| Interaction | HTTP example | Purpose |
|---|---|---|
| Read | GET [base]/Patient/{id} | Fetch a single resource by id. ( blog.hl7.org) |
| VRead (version read) | GET [base]/Patient/{id}/_history/{vid} | Fetch a specific version of a resource. |
| Search | GET [base]/Observation?patient=123&_count=50 | Query resources using parameters. ( HL7) |
| Create | POST [base]/Patient (body = Patient JSON) | Create a new resource. |
| Update | PUT [base]/Patient/{id} | Replace resource at id. |
| Patch | PATCH [base]/Patient/{id} | Partial update. |
| Delete | DELETE [base]/Patient/{id} | Remove (logical/physical depending on server). |
Search — How Querying Works
| Feature | What it does | Example |
|---|---|---|
| Search parameters | Predefined parameters (e.g., patient, code, date) control filters. ( FHIR Build ) | GET [base]/Observation?patient=123&code=29463-7 |
| Modifiers & prefixes | Operators like :missing, :contains, numeric prefixes gt, lt. ( HL7 ) | GET [base]/Observation?value-quantity=gt200 |
| _include / _revinclude | Pull related resources in one call (e.g., include Patient when returning Observations). ( HL7) | GET [base]/Observation?patient=123&_include=Observation:patient |
| _count / paging | Control page size and navigate pages via link headers. |
Note: Search behavior may vary by server/vendor — always check the server’s conformance statement and docs (servers may limit parameters or support extra ones). (Microsoft Learn)
Request
GET FHIR Patient Resource Example
Accept: application/fhir+json
{
"resourceType": "Patient",
"id": "123",
"name": [{ "family": "Doe", "given": ["Jane"] }],
"gender": "female",
"birthDate": "1980-04-01"
}
Conformance & Capability Statement
| Item | Purpose |
|---|---|
| Capability Statement | Machine-readable document that lists which interactions, search parameters, and resources a FHIR server supports. Use it as the canonical contract when integrating with a server. (blog.hl7.org) |
| Conformance check | Always retrieve [base]/metadata before integration to discover server behavior. |
Security: OAuth2 + SMART on FHIR
| Topic | Key detail |
|---|---|
| Auth protocol | OAuth2 (authorization code, client credentials for services). SMART on FHIR extends OAuth2 for EHR app context. (docs.smarthealthit.org) |
| Scopes | Fine-grained access (e.g., patient/Observation.read, user/Patient.*). |
| Tokens | Short-lived access tokens + refresh tokens; always use TLS. |
| SMART app launch | App launch context & patient selection via launch parameter and openid flows. (SMART Health IT) |
| Best practices | Validate redirect URIs, use PKCE for public clients, rotate secrets, log token use. ( docs.smarthealthit.org) |
Security note: Implementations must follow security best practices; OAuth2 alone is not enough if misimplemented — carefully follow SMART and vendor guidance. ( docs.smarthealthit.org)
Advanced Interactions & Patterns
| Pattern | Purpose | When to use |
|---|---|---|
| Batch / Transaction | Submit multiple operations in one HTTP request (POST [base]/$transaction) | Atomic updates across resources |
| Bulk Data (Flat FHIR / $export) | Export large datasets for analytics or research (Bulk Data API) | Population-level exports, claims/research workflows. Download FHIR Bulk Data API PPT (HL7) |
| Operations ($operation) | Server-level or resource-level custom operations (e.g., $everything) | When standard interactions are insufficient |
| Subscriptions | Receive notifications for resource changes | Real-time updates to downstream systems |
Error Handling & Responses
| Status | Meaning | Typical Body |
|---|---|---|
| 200 / 201 | Success / created | Resource or OperationOutcome |
| 400 | Bad request | Operation Outcome with issues |
| 401 / 403 | 401 / 403 | Check tokens, scopes |
| 404 | Not found | Requested id not present |
| 409 | Conflict | Versioning or business rule conflict |
| 422 | Unprocessable | Validation errors (OperationOutcome) |
OperationOutcome is the standard FHIR resource used to convey errors and warnings back to clients.
Best Practices for Integrators
1. Always check the server’s CapabilityStatement
Before integrating with any FHIR server, call:
GET [base]/metadata
This tells you exactly which resources, search parameters, interactions, profiles, and security protocols the server supports. Never assume all servers behave the same.
2. Use paging and _count wisely
FHIR servers often limit results.
Use _count to request smaller batches and follow the returned link headers for pagination. This improves performance and avoids timeouts or throttling.
3. Implement robust authentication using OAuth2 / SMART on FHIR
Use:
- Authorization Code Flow
- PKCE for public/mobile apps
- Proper scope management
- TLS everywhere
- Token rotation + short-lived access tokens
Always validate tokens and scopes before allowing access to sensitive data.
4. Map terminologies consistently
FHIR relies on medical terminologies like:
- LOINC (labs/vitals)
- SNOMED CT (clinical terms)
- ICD-10 (diagnoses)
Mapping your system’s internal codes to standard vocabularies improves interoperability and ensures accurate analytics.
5. Implement idempotent operations
For update-heavy workflows, ensure your calls:
- For update-heavy workflows, ensure your calls:
- Avoid duplicate data
- Log conflicts
FHIR versioning helps, but you must design for safe updates.
6. Apply input validation
Validate incoming JSON/XML against:
- FHIR resource structure
- Profiles
- Terminology bindings
Reject malformed or incomplete resources early.
7. Monitor and log everything
Track:
- API usage
- Failed logins
- Token errors
- Response times
- Search parameters used
This supports compliance, debugging, and auditing.
How Vendors & Cloud Providers Implement FHIR Search
Many cloud vendors (Azure Health Data Services, AWS HealthLake, Google Cloud Healthcare) implement the FHIR search and API spec but may add extensions, rate limits, or advanced query features. Always test against the specific vendor’s FHIR store. ( Microsoft Learn)
Frequently Asked Questions:
A FHIR API is used to read, write, and query healthcare data — such as patients, lab results, encounters, conditions, and medications — using standard RESTful web calls. This allows different healthcare applications, EHRs, and mobile apps to exchange data in a consistent and interoperable format.
FHIR search works by using predefined search parameters such as patient, code, date, and others. Clients make GET requests that include these parameters (e.g., ?patient=123&code=xyz). FHIR servers then return matching resources and can include related resources, pagination, sorting rules, modifiers, and filters depending on server capabilities.
FHIR APIs are typically secured using OAuth2 and SMART on FHIR. OAuth2 manages authentication and authorization, while SMART adds additional layers such as app context, launch flows, and granular scopes (like patient/Observation.read). Implementations should always use TLS, short-lived tokens, PKCE for public clients, and strict scope validation.
Related Resources:
FHIR Basics | FHIR API and Security | FHIR Security Best Practices | FHIR Interoperability | FHIR vs HL7 | FHIR Integration | FHIR workflow automation | FHIR For SDOH | FHIR Implementation Cost and Guide
More About SocialRoots.ai Healthcare Suite:
Pillar Community Healthcare Management system
About SocialRoots.ai Interoperability Solutions;
Legacy EHR Migration – Guaranteed 90 Days shift
EHR Integration and Interoperability Solutions
Pre-built Salesforce Integration.
Sources & further reading (authoritative)
- HL7 FHIR HTTP (RESTful) interactions & spec. ( blog.hl7.org)
- SMART on FHIR authorization & best practices. ( docs.smarthealthit.org)
- Cloud vendor FHIR search docs (Azure / AWS / GCP examples). ( Microsoft Learn)