Modern healthcare applications rarely work in isolation.
A patient portal may need data from an Electronic Health Record (EHR). A remote patient monitoring application may need to exchange observations with a clinical system. A telehealth platform may need patient demographics, appointments, medications, or diagnostic information.
The challenge is that healthcare systems can represent and exchange data differently.
FHIR, or Fast Healthcare Interoperability Resources, provides a standardized approach for exchanging healthcare information through structured resources and RESTful APIs.
For .NET developers, FHIR can be integrated into healthcare applications using ASP.NET Core and libraries such as the Firely .NET SDK.
In this article, we will build a simple FHIR-ready healthcare API using C# and ASP.NET Core. We will look at:
What FHIR means from a developer's perspective
How FHIR resources are structured
How to create an ASP.NET Core healthcare API
How to use the Firely .NET SDK
How to retrieve patient information from a FHIR server
How to retrieve clinical observations
How to structure the application cleanly
Important authentication and security considerations
Common mistakes developers should avoid
The examples are designed for learning and architecture demonstration. Production healthcare applications require additional security, validation, authorization, auditing, testing, and regulatory review.
What Is FHIR?
FHIR stands for Fast Healthcare Interoperability Resources.
It is a healthcare interoperability standard developed by HL7 for representing and exchanging healthcare information electronically.
Instead of treating an entire medical record as one large data structure, FHIR organizes healthcare information into individual resources.
Examples include:
Patient
Practitioner
Observation
Condition
Encounter
MedicationRequest
AllergyIntolerance
Appointment
DiagnosticReport
CarePlan
Each resource represents a particular healthcare concept.
For example, a Patient resource can represent demographic information, while an Observation resource can represent a blood-pressure reading, laboratory value, temperature, or other clinical measurement.
A simplified interaction might look like this:
Patient Application
|
v
ASP.NET Core API
|
v
FHIR Integration Service
|
v
FHIR Server
|
+---- Patient
+---- Observation
+---- Condition
+---- MedicationRequestThis structure allows applications to exchange healthcare information through well-defined resource models.
Why Use FHIR in a Healthcare Application?
Imagine you are developing a patient application that needs information from an EHR.
Without a common interoperability model, your application may need a custom integration for every healthcare system.
FHIR creates a standard interface around healthcare information.
A healthcare application could request:
GET /Patient/123to retrieve a patient.
It could then request observations belonging to that patient:
GET /Observation?patient=123A real implementation may include additional profiles, terminology requirements, authorization scopes, identifiers, search parameters, and implementation-guide rules.
However, the resource-based model gives developers a common foundation.
Our Example Architecture
For this example, we will place our ASP.NET Core API between the application and the FHIR server.
Web / Mobile / Clinical Application
|
v
ASP.NET Core API
|
v
Healthcare Services
|
v
FHIR Client Layer
|
v
FHIR ServerThere are several advantages to this approach.
The frontend does not need to know the details of every FHIR integration.
The API can also provide a central location for:
Authentication
Authorization
Request validation
Data transformation
Audit logging
Error handling
Rate limiting
Business rules
Monitoring
It also avoids putting healthcare-integration logic directly inside controllers.
Step 1: Create the ASP.NET Core Web API
Create a project from the command line:
dotnet new webapi -n HealthcareFhirApi
cd HealthcareFhirApiASP.NET Core supports both controller-based APIs and Minimal APIs.
For this example, we will use controllers because they make the separation between the API layer and healthcare integration layer easy to demonstrate.
Step 2: Install the FHIR .NET SDK
We will work with FHIR R4 in this example.
Install the appropriate package:
dotnet add package Hl7.Fhir.R4The Firely .NET SDK provides .NET classes corresponding to FHIR resources.
For example:
Patient
Observation
Condition
Encounter
MedicationRequestInstead of manually parsing healthcare JSON into custom models, we can work with typed FHIR objects.
Add the namespaces where required:
using Hl7.Fhir.Model;
using Hl7.Fhir.Rest;Step 3: Add the FHIR Server Configuration
Do not hardcode environment-specific FHIR endpoints throughout the application.
Add a configuration section to appsettings.json.
{
"Fhir": {
"ServerUrl": "https://your-fhir-server.example/fhir"
}
}For real healthcare environments, credentials and sensitive configuration should be handled through an appropriate secrets-management mechanism rather than committed to source control.
Create a configuration model:
public class FhirOptions
{
public string ServerUrl { get; set; } = string.Empty;
}Register the configuration in Program.cs:
var builder = WebApplication.CreateBuilder(args);
builder.Services.Configure<FhirOptions>(
builder.Configuration.GetSection("Fhir"));
builder.Services.AddControllers();
var app = builder.Build();
app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();We now have the basic ASP.NET Core API structure.
Step 4: Create a FHIR Service
Controllers should not be responsible for configuring FHIR clients and implementing healthcare-integration logic.
Create an interface:
using Hl7.Fhir.Model;
public interface IFhirService
{
Task<Patient?> GetPatientAsync(string id);
Task<IReadOnlyList<Observation>>
GetPatientObservationsAsync(string patientId);
}Next, create the implementation.
using Hl7.Fhir.Model;
using Hl7.Fhir.Rest;
using Microsoft.Extensions.Options;
public class FhirService : IFhirService
{
private readonly string _serverUrl;
public FhirService(IOptions<FhirOptions> options)
{
_serverUrl = options.Value.ServerUrl;
}
private FhirClient CreateClient()
{
return new FhirClient(_serverUrl);
}
public async Task<Patient?> GetPatientAsync(string id)
{
var client = CreateClient();
try
{
return await client.ReadAsync<Patient>(
$"Patient/{id}");
}
catch (FhirOperationException ex)
when (ex.Status == System.Net.HttpStatusCode.NotFound)
{
return null;
}
}
public async Task<IReadOnlyList<Observation>>
GetPatientObservationsAsync(string patientId)
{
var client = CreateClient();
var bundle =
await client.SearchAsync<Observation>(
new[]
{
$"patient=Patient/{patientId}"
});
if (bundle?.Entry == null)
{
return Array.Empty<Observation>();
}
return bundle.Entry
.Where(entry => entry.Resource is Observation)
.Select(entry => (Observation)entry.Resource)
.ToList();
}
}This service performs two operations.
The first reads an individual Patient resource.
The second searches for Observation resources associated with a patient.
The important architectural point is that the controller does not need to know how FHIR communication works.
Step 5: Register the FHIR Service
Register the service with ASP.NET Core dependency injection.
Update Program.cs:
var builder = WebApplication.CreateBuilder(args);
builder.Services.Configure<FhirOptions>(
builder.Configuration.GetSection("Fhir"));
builder.Services.AddScoped<IFhirService, FhirService>();
builder.Services.AddControllers();
var app = builder.Build();
app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();The integration service can now be injected into API controllers.
Step 6: Create the Patient Controller
Create a controller for retrieving patient information.
using Microsoft.AspNetCore.Mvc;
[ApiController]
[Route("api/patients")]
public class PatientsController : ControllerBase
{
private readonly IFhirService _fhirService;
public PatientsController(IFhirService fhirService)
{
_fhirService = fhirService;
}
[HttpGet("{id}")]
public async Task<IActionResult> GetPatient(
string id)
{
var patient =
await _fhirService.GetPatientAsync(id);
if (patient == null)
{
return NotFound();
}
return Ok(patient);
}
}Calling:
GET /api/patients/123causes our ASP.NET Core application to request the corresponding Patient resource from the FHIR server.
Step 7: Retrieve Clinical Observations
Now add an endpoint for observations.
[HttpGet("{id}/observations")]
public async Task<IActionResult> GetObservations(
string id)
{
var observations =
await _fhirService
.GetPatientObservationsAsync(id);
return Ok(observations);
}A request might look like:
GET /api/patients/123/observationsThe resulting FHIR resources may contain measurements such as:
Blood pressure
Heart rate
Body temperature
Oxygen saturation
Laboratory values
Body weight
The exact interpretation depends on the coding systems and profiles used by the connected healthcare environment.
Understanding a FHIR Observation
A simplified observation can conceptually contain:
{
"resourceType": "Observation",
"status": "final",
"code": {
"text": "Heart rate"
},
"subject": {
"reference": "Patient/123"
},
"valueQuantity": {
"value": 72,
"unit": "beats/minute"
}
}
Join the conversation! Your thoughts help the community grow.