How to Build a FHIR Server Using HAPI FHIR or Azure API for FHIR?

Posted in HL7

FHIR is a well-known standardized protocol developed by HL7 to solve challenges related to data interoperability. FHIR simplifies how information is structured and exchanged throughout the healthcare system. Complex data is broken down into standardized resources that represent real-world entities such as a Patient, Observation, or Medication, with clearly defined fields and relationships. FHIR is built on RESTful APIs; developers can interact with data using standard HTTP methods (GET, POST, PUT, DELETE). This makes it intuitive and accessible for developers familiar with modern API development. A FHIR server standardizes messages and securely exchanges data across diverse systems. Various types of FHIR servers exist to suit different needs, including open-source FHIR servers like HAPI FHIR, cloud-based options such as the Azure FHIR server, and the AWS FHIR server. Let’s get into more details.

Taking Broken, Fragmented Data with a FHIR Server

A patient’s journey is often long and complex, involving multiple doctors, hospitals, laboratories, pharmacies, and more. Each uses its own computer system, fragmenting healthcare data and storing it in isolated silos.

This disconnected way of working has some serious consequences:

• Less Effective Patient Care: Doctors often don’t have a complete, real-time picture of a patient’s health history. This leads to repeated tests, delayed diagnosis, and treatment decisions.
• Wasted Time and Money: Our teams spend a lot of time copying information, entering data they already have, or trying to make custom connections between systems, which takes away valuable time and money that could be used directly for patient care or new ideas.
• More Rules and Risks: Dealing with strict rules about patient privacy and security, like HIPAA or GDPR, becomes much more complicated and expensive when sensitive data is spread across many separate systems that don’t follow the same criteria.

What is a FHIR Server?

FHIR is the standard data language, and the FHIR server is its interpreter. It’s a secure, dedicated system explicitly built to store, manage, validate, and provide healthcare information in the FHIR format. 

Here are some of the capabilities of a strong FHIR server:

• Single Source of Information: It becomes the trusted, central repository for all your FHIR-formatted data. This single, reliable source makes sure information is consistent and accurate across all your connected applications and care pathways.

• Secure, Standard Sharing: The FHIR server offers its functions through RESTful APIs. They allow different healthcare applications, like EHRs, patient portals, telehealth systems, or medical devices, to securely ask for patient data or send updates in a standard way.

• Structures Data: Before accepting new data, a FHIR server thoroughly checks it against the set standards. This process guarantees incoming information follows the correct structure, format, and rules, actively stopping bad or incorrect data from getting into your system.

• Stores Complete History: Healthcare data changes constantly. A smart FHIR server carefully tracks every change to a piece of information, keeping a complete, unchangeable history. This is crucial for audits, legal reasons, and managing complex tasks.

• Maintains Security and Privacy: Handling sensitive patient information (PHI) demands the highest level of security. A FHIR server is built with strong, multi-layered security features, including:

1. • Detailed Access Controls: Using industry standards like OAuth 2.0 and OpenID Connect, it ensures that only authorized people or applications can see specific parts of the data based on their roles and permissions.
   • Data Encryption: All data is encrypted when stored (at rest) and moving across networks (in transit), providing a strong shield against unauthorized access.
   • Complete Activity Logs: Every action taken with the FHIR server, every data request, change, or attempted access, is carefully recorded. These detailed logs are essential for meeting rules and quickly investigating any security issues.

Main Benefits of FHIR Server Architecture

What is Azure FHIR Server?

While the benefits of a FHIR server are clear, maintaining it requires significant upfront money for the following: 

• Equipment
• Highly specialized technical skills
• Constant ongoing work
• Continuous vigilance against new threats and changing rules. 

Due to these reasons, a managed FHIR service in a cloud environment becomes incredibly useful.

Microsoft Azure offers the FHIR service within Azure Health Data Services (AHDS). It is a partnership that expertly handles modern healthcare data management issues, allowing your organization to focus on providing the best patient care and driving medical innovation.

Benefits of Choosing Azure

1. Focus on Innovation, not IT maintenance: Azure handles all the operational work as a PaaS solution. This means Microsoft manages the underlying hardware, handles software updates, sets up security, and scales the resources. 

Your IT teams can instead use their expertise to build new patient applications and lead strategic projects that boost patient outcomes and your organization’s ROI. 

2. Security and Built-in Compliance: Healthcare data demands the highest level of protection and compliance. Azure’s FHIR service is carefully designed from the ground up, and it has a deep understanding of strict healthcare regulations, including HIPAA and GDPR. It provides:

• Strong access controls use industry standards like Microsoft Entra ID (formerly Azure Active Directory). Based on their roles, authorized people or applications can only see specific parts of the data.
• Complete data encryption shields against unauthorized access, both when it’s stored (at rest) and when it’s moving across networks (in transit).
• Detailed activity logs maintain every action with the FHIR service, carefully recorded, providing unchanging logs crucial for meeting rules and quickly investigating any security issues.
• Features like Azure Private Link allow your internal systems to connect privately and securely to the FHIR service over Microsoft’s highly protected network, greatly reducing exposure to the public Internet.

3. Flexible Scaling: Healthcare organizations experience changing data demands from busy periods during clinic hours to huge data imports for research or mergers. Azure’s FHIR service is flexible and easily scales. 

It automatically adjusts its computing power to handle different workloads, ensuring consistent, high performance even during busy times. Its pay-as-you-go approach helps organizations stay on budget. One must pay for the computing resources, avoiding big upfront costs.

4.Future-Proofing Your Investment: Microsoft’s strong commitment to FHIR and healthcare data sharing is clear in its ongoing investment in Azure Health Data Services. Using this managed service, your organization automatically benefits from continuous platform updates, new features, and guaranteed adherence to the latest FHIR standards. 

This, too, is all without the significant internal work of managing these complex upgrades. This ensures your health data systems stay current, compliant, and fully capable of supporting all future innovations in healthcare.

5. Collaboration and Coordinated Care: By using a standard FHIR server, your organization naturally becomes a more connected and attractive partner within the broader healthcare community. This greatly simplifies secure data sharing with HIEs, other provider networks, important research institutions, and innovative third-party healthcare applications built on open standards like SMART on FHIR. 

This ability to collaborate is essential for providing coordinated care, supporting large-scale public health efforts, and successfully taking part in the evolving world of value-based care models.

Building Solution with Azure FHIR

When you build a solution with Azure’s FHIR service, you’ll typically combine several Azure pieces to create a complete, secure, and scalable system for healthcare data:

• FHIR Server: This is the core, managed part of the system (the FHIR service within Azure Health Data Services).
• Apps/Clients: These are your web, mobile, or backend applications that send or receive FHIR data. They use OAuth 2.0 for secure access.
• Data Integration & ETL: Azure services like Azure Data Factory, Logic Apps, or Azure Functions help you move and transform data from older systems (like HL7 v2, CDA, or CSV) into FHIR, or trigger actions based on changes in FHIR data.
• Analytics & Business Intelligence: Tools like Azure Synapse Analytics, Azure Databricks, or Power BI use your FHIR data (often exported in large batches) for big-picture analysis, reports, and advanced insights.
• Security Layer: On top of the FHIR service’s built-in security, Azure AD, Azure Private Link, virtual networks, and firewalls create a strong defense and manage who can access what.
• Monitoring and Logging: Azure Monitor and Log Analytics give you full control over checking API performance, errors, how the system is being used, and keeping detailed activity records.

Setting Up a FHIR Server on Azure

Azure makes deploying a FHIR server straightforward, whether you’re just trying things out or going live with a full system.

1. What You Need:

• An active Azure account.
• Permissions in Azure that let you create resources (like being a “Contributor” or “Owner” for a group of resources).

2. Turn On the Healthcare API:

Before you set up a FHIR service, you need to tell your Azure subscription to allow the necessary services. You usually only do this once:

Bash

az provider register –namespace Microsoft.HealthcareApis

3. Deploy Your FHIR Service:

You can do this through the Azure Portal (a web interface), using the Azure Command Line Interface (CLI), or with code templates like ARM or Bicep. Here’s a CLI example:

Bash

az healthcareapis fhir create \

  –resource-group myResourceGroup \

  –name myFhirService \

  –location eastus \

  –kind fhir-R4 # Specify FHIR R4 version

This command sets up a new FHIR service in the group and region you pick.

4. Check If It’s Working:

Once it’s deployed, you can check if your FHIR server is ready by looking at its /metadata endpoint. This is a special FHIR resource that tells you what the server can do:

Plaintext

GET https://<your-fhir-service-name>.azurehealthcareapis.com/metadata

If it works, you’ll get back a “CapabilityStatement” which confirms the FHIR version and the actions the server supports.

5. Secure Your Data:

This is super important. You’ll set up Azure AD (Microsoft Entra ID) to control who can access your FHIR data. This involves:

• Registering Your Apps: You’ll register any application that needs to talk to your FHIR server (like a web app or mobile app) in Azure AD.
• Giving Permissions (RBAC): You’ll assign specific roles (like “FHIR Data Reader” or “FHIR Data Contributor”) to people or programs that need access. These roles define exactly what they’re allowed to do.
• How Access Works (OAuth 2.0): When an app wants to connect to your FHIR server, it first gets an OAuth 2.0 access token (a digital key) from Azure AD. This key includes information about what the app is allowed to do (like “read patient data”). The app then includes this key in all its requests to the FHIR server. The FHIR server checks the key and makes sure the app has the right permissions.

For very precise access control, especially for third-party or patient apps, use SMART on FHIR scopes. These allow apps to ask for access to only very specific data (e.g., just the patient’s own record, or specific types of lab results).

Capabilities of Azure FHIR 

Azure API for FHIR is designed to be a complete platform for healthcare data, offering advanced features that are crucial for modern solutions:

Extracting Data

• Bulk Import: You can efficiently upload large amounts of FHIR data or convert data from older formats like HL7 v2, CDA, or CSV using Azure Data Factory tools.
• Bulk Export: This FHIR feature lets you pull out huge datasets (for research or analysis) in a standard format called NDJSON. You can export data for the whole system, specific groups, or individual patients.

Automatic Integrations (Event-Driven):

• Azure Event Grid: You can set this up to get real-time notifications whenever a FHIR resource changes (like when a new patient is added or an old one is updated). This lets other systems react instantly.
• Azure Functions / Logic Apps: These serverless tools let you automate tasks based on FHIR events, like sending alerts, running data transformations, or doing custom work automatically.

SMART on FHIR: 

• Full support for the SMART (Substitutable Medical Applications and Reusable Technology) on FHIR specification. This enables the development of a secure, standards-based ecosystem of third-party applications that can seamlessly integrate with your FHIR server, providing tailored patient and clinician experiences.

Tools for Developers: 

Azure provides a rich set of tools to help developers work faster:

• SDKs: Official software development kits are available for popular programming languages like .NET, Java, and JavaScript, making it easier to build apps that talk to FHIR.
• Postman Collections: Pre-built sets of API requests for Postman make it quick to test and explore the FHIR API.
• FHIR Validator: These tools help you check if your FHIR data follows the rules and your custom settings, ensuring good data quality.
• Sandbox Environments: You can easily set up isolated environments for trying out ideas, developing, and testing safely.

Security and Compliance

Security is non-negotiable in healthcare. Azure API for FHIR is carefully built with multiple layers of security to protect sensitive Protected Health Information (PHI). It offers:

Data Encryption: 

As we mentioned, your data is protected by encryption when it’s sitting in storage (at rest) and moving across networks (in transit, using secure protocols like TLS 1.2+). You can even use your own encryption keys for more control.

Complete Activity Logs: 

Every single action taken with the FHIR server (every time someone accesses, updates, queries, or deletes data) is recorded. These detailed audit logs are essential for meeting compliance rules and for figuring out what happened if there’s ever a security issue.

Access Rules and Least Privilege: 

Access is strictly controlled using Azure’s Role-Based Access Control (RBAC). This means people and applications are given only the bare minimum permissions.

Network Security:

• Private Link: This allows private, secure connections from your Azure Virtual Networks directly to the FHIR service, completely bypassing the public internet. This significantly reduces potential points of attack.
• Virtual Network (VNET) Integration: This lets the FHIR service talk securely with other resources inside your Azure VNET.
• Firewall Rules: You can set up rules to restrict access to the FHIR service to only specific IP addresses or ranges.

Certifications for Compliance: 

Azure API for FHIR has been certified and meets major global and regional healthcare regulations and standards, including HIPAA, GDPR, HITRUST, ISO 27001, SOC 2, and more. This gives your organization a strong foundation for meeting its compliance obligations.

Real-World Uses: Azure API for FHIR 

• Unified Patient Records: Combine patient data from different EHRs, lab systems, and medical devices into a comprehensive patient record. This centralized information helps with understanding population health, coordinating care, and supporting clinical decisions.

• Next-Gen Health Apps: Build SMART on FHIR applications, like easy-to-use patient portals, advanced remote monitoring tools, secure medication management apps, or specialized tools for doctors. These innovations connect safely and work across different healthcare systems and devices.

• Advanced Analytics and AI: Feed the standardized FHIR data into powerful analytical platforms like Azure Synapse Analytics or Azure Databricks, or directly into Azure Machine Learning projects. This enables sophisticated predictions about patient risk, quality improvements, and smarter operations.

• Managing Research Data Safely: Securely manage and remove patient identifiers from large datasets for clinical trials, studies of real-world evidence, and academic research, ensuring privacy while speeding up scientific discoveries.

• Automated Reports for Regulators: Use FHIR’s structured data and the FHIR server’s activity logs to automatically create the necessary reports and simplify paperwork for regulators and payers.

• Better Care Coordination: Make it possible to share data securely and in real-time between hospitals, clinics, specialists, and community health providers. This leads to truly connected care and clearly better results for patients.

Best Practices of Azure FHIR

The following practices can help you get the most out of your Azure FHIR setup: 

• Use the Managed Service: Focus your engineering talent on building great applications, not on maintaining complex infrastructure. Make the most of Azure’s managed services.
• Be Strict with Permissions (RBAC): Always give people and programs only the minimum permissions they need. Regularly check and review these roles.
• Watch and Audit Constantly: Use Azure Monitor and Log Analytics to keep an eye on performance, check security, and quickly respond to any issues.
• Automate Everything: Use Infrastructure as Code (IaC) and CI/CD pipelines for consistent, repeatable, and error-free deployments of your systems.
• Connect for Insights: Link your FHIR service to Azure Synapse, Power BI, or Azure Machine Learning tools to turn raw data into smart decisions and predictive models.
• Plan for Growth: Design your solutions with FHIR’s automatic scaling in mind, and think about data partitioning strategies for very large amounts of data or for serving many different organizations.
• Lock Your Network: Set up strong network security using Azure Private Link, virtual network integration, and precise firewall rules.
• Check Your Data: Use FHIR Validator tools to make sure all data coming in and out of your system follows the rules and your custom settings, which helps maintain data quality.

The Future of Azure Health Data Services 

Microsoft will retire the standalone Azure API for FHIR by September 30, 2026. The clear supported path for all customers is to move their existing systems to the FHIR service within Azure Health Data Services (AHDS). 

AHDS is Microsoft’s unified platform for healthcare data, bringing together FHIR, DICOM (for medical imaging data), and MedTech services (for data coming from medical devices) into one integrated place. This evolution offers even better features and a more complete way to handle health data.

Simple Code Example: Using Your FHIR Server

Here’s a quick example using curl to create and ask for a Patient record from your Azure FHIR service. You’ll need an access_token from Azure AD.

Creating a Patient Record:

Bash

curl -X POST \

  https://<your-fhir-service-name>.azurehealthcareapis.com/Patient \

  -H “Authorization: Bearer <access_token>” \

  -H “Content-Type: application/fhir+json” \

  -d ‘{

    “resourceType”: “Patient”,

    “name”: [{ “use”: “official”, “family”: “Smith”, “given”: [“John”] }],

    “gender”: “male”,

    “birthDate”: “1980-01-01”

  }’

 

Asking for a Patient Record:

Bash

curl -X GET \

  https://<your-fhir-service-name>.azurehealthcareapis.com/Patient?name=Smith \

  -H “Authorization: Bearer <access_token>”

 

Architecture Diagram (How It Works)

Plaintext

+———————+              +————————————-+

| Your Apps & Clients |              | Azure AD (Microsoft Entra ID)       |

| (Web, Mobile, Data) |              | (Handles Logins & Permissions)      |

+———-+———-+              +——————+——————+

           |                              ^                  ^

           | (Secure Key)                 | (Checks Key)     | (Sets Roles)

           v                              |                  |

+———————————————————————–+

|            Azure Health Data Services (AHDS) FHIR Service             |

|                                                                       |

|   +—————————————————————–+ |

|   |                  FHIR Server (Managed for You)                  | |

|   | – FHIR R4 Connection Point                                      | |

|   | – Stores Your Data                                              | |

|   | – Handles Data Actions (Create, Read, Search, Export, etc.)     | |

|   | – Checks Data Quality                                           | |

|   | – Keeps Data History                                            | |

|   | – Security (Encryption, Activity Records)                       | |

|   +—————————————————————–+ |

|                                                                       |

|   +—————————————————————–+ |

|   |                   Other AHDS Services (Built-in)                | |

|   | – DICOM Service (Medical Image Data)                            | |

|   | – MedTech Service (Gets Data from Medical Devices)              | |

|   +—————————————————————–+ |

+———————————————————————–+

           | (When FHIR Data Changes)

           v

+——————-+

| Azure Event Grid  |

+———+———+

          |

          v

+———————————–+

| Azure Functions / Logic Apps      |

| (Automatic Tasks, Workflows)      |

+———————————–+

          |

          v

+———————————–+

| Azure Synapse Analytics / Power BI|

| Azure Machine Learning / Databricks |

| (Smart Data Analysis, AI, Reports)|

+———————————–+

          |

          v

+———————–+

| Azure Data Lake Storage / Storage Accounts |

| (Where Large Data Sits)   |

+———————–+

What Is HAPI FHIR Server?

What is a HAPI server? It’s a Java-based, open-source framework that fully implements the HL7® FHIR® standard. It’s widely used across the healthcare industry to build systems that exchange, store, and validate healthcare data.

Key Features of HAPI FHIR Server:

• Open Source and Extensible: HAPI FHIR is freely available under the Apache 2.0 license, allowing for extensive customization and use in personal and commercial projects. 
• Comprehensive FHIR Implementation: It supports various FHIR versions (R4, R5, etc.) and provides a complete implementation of the FHIR specification, including RESTful operations (create, read, update, delete, search, history, etc.), terminology services, and validation.
• Multiple Server Types:
• • Plain Server (Facade): This acts as a facade layer where you provide the backend data storage and retrieval logic, while HAPI FHIR handles the HTTP processing, serialization, and FHIR REST semantics. This is useful for integrating FHIR with existing data sources.
  • JPA Server: This is a full-fledged FHIR server implementation with its own database schema. It handles all storage and retrieval logic against a relational database (like PostgreSQL, MySQL, etc.) without requiring you to write custom data access code.
  • JAX-RS Server: A community-supported module for building FHIR servers based on JAX-RS.
• Validation Tools: HAPI FHIR includes robust validation tools to ensure that FHIR resources conform to official FHIR profiles and implementation guides, helping maintain data quality and interoperability.
• Terminology Services: It enables effective integration with standard code systems like SNOMED CT and LOINC, facilitating the proper handling and validation of medical terminologies.
• Client API: While focusing on the server, HAPI FHIR also provides a client API for applications to interact with external FHIR servers.
• Command-Line Tool (CLI): A command-line interface for managing FHIR resources, starting local FHIR servers, uploading terminologies, and migrating databases.
• Deployment Flexibility: Can be deployed in various environments, including Windows, macOS, Linux, Docker, and cloud platforms

Real-World Use Cases

Here’s how organizations are putting HAPI FHIR to work:

• EHR Integration: Streamlining data exchange between multiple Electronic Health Record systems.
  
• mHealth Apps: Powering mobile apps that give patients secure access to their health data.
  
• Interoperability Projects: Enabling health data sharing between hospitals, labs, and public health agencies.
  
• AI & Decision Support: Feeding structured data into clinical algorithms and machine learning models.
  
• Research & Analytics: Aggregating clean, validated health data for population health dashboards and predictive insights.
  
• Prototyping: Setting up test servers quickly to explore FHIR-based app development.

Seamless FHIR Integration with Folio3 Digital Health

At Folio3 Digital Health, we specialize in bridging the gap between legacy healthcare systems and modern interoperability standards. Our comprehensive HL7 and FHIR integration services are designed to seamlessly link disconnected EHRs, LIS, and other healthcare applications. We focus on making data more accessible, interoperable, and compliant with standards like HIPAA and GDPR, without disrupting day-to-day operations. From HL7 v2 transformations to full-scale FHIR implementations, we build smart, future-ready solutions tailored to your needs. 

Conclusion

Microsoft Azure, with its FHIR service inside Azure Health Data Services, provides an easy-to-use and super secure way to facilitate interoperability. By using these managed services, strong security tools, and built-in analytics, your organization can build smart solutions that directly lead to better patient outcomes, empower healthcare providers, and speed up vital research.

Frequently Asked Questions

What version of FHIR does Azure support?

The standalone Azure API for FHIR and the FHIR service within Azure Health Data Services currently support FHIR R4 (version 4.0.1).

Is Azure API for FHIR compliant with HIPAA?

Yes. Azure API for FHIR meets HIPAA, GDPR, HITRUST, and other major compliance standards. Microsoft also provides Business Associate Agreements (BAAs).

What is an open source FHIR server?

An open source FHIR server is a freely available, community-supported implementation of the FHIR standard that allows developers to store, manage, and exchange healthcare data. It is customizable, self-hosted, and can be extended to fit specific project needs.

Is the Python FHIR server different from Azure FHIR?

Yes. A Python FHIR server is ideal for testing, research, or small-scale projects. The Azure FHIR server is a fully managed, enterprise-grade solution designed for secure, scalable, and compliant healthcare data exchange.

About the Author