In this unit we will focus on how to create a FHIR server.

The objective is that by the end of this unit you will have an idea of what is involved in creating a FHIR server and strategies to include one in your architecture.

Although many people have been working with FHIR for a long time, we know from experience that many times not everyone is aware of what functionalities a FHIR server should or can have and what your obligations are as the creator of a server, so we will review them.

We will present the general concepts for server libraries (how to perform common tasks for FHIR servers: metadata, CRUD methods, etc.) and then describe how each library allows you to do each task.

So, this unit in fact contains 3 different subunits on how to use each library (Java, C#,JavaScript).

This unit DOES NOT CONTAIN MicroAssignments: we want you to focus on solving the assignments.

What you'll learn

After Unit 3, you will be able to:

This specific subunit talks about implementing a facade in C#/DOTNET

Note:

When we began to work in this Unit, we found out that there are NO Open Source libraries for creating a C#-based FHIR Server Facade. There is a lot of open source for creating native FHIR servers, including products by Microsoft, IBM, etc. But they are not useful to create a FHIR Facade.

So we gave up, and for years, our Unit 3 was about Java and node.js

However, a bright alumni of our course (Chandima Fonseca (chandima.fonseka@ontariohealth.ca) from Ontario Health - respect!!!) contributed with a FHIR Server built using only the FHIR C#/.NET Library. Everything else (routes, mappers, handling of the HTTP requests, etc.) is handled by the code that you can see: no special libraries.

The original Chandima's project handled read/write and used a database instead of an API, we adapted this project to be equivalent to our Java and node.js projects.

It's open-source with no support and no documentation...but it works, at least to demonstrate what a FHIR Server Facade needs to do.

To work with this project and FHIR R4, you will need DotNet Version 6.0.201 (Run dotnet --version)

Throughout these sections, you will see three distinct icons:

Sometimes to illustrate a method we use both examples and recipes, and sometimes only examples, depending on the complexity of the subject.

Our project has four components:

You can use Visual Studio Code or Visual Studio (v16 or higher)

In fact we used Visual Studio Code to run the project.

fhir-server-CSharp: The main project, this component handles the incoming HTTP requests, validates them, implements the routes for each FHIR Resource class, and returns the response to the FHIR Client.

fhir-server-dataaccess: Implements access to the Legacy API/Database

fhir-server-entity-model: Defines the data model for the Legacy API/Database

fhir-server-mapping: Transform an instance of the Legacy API entities in a FHIR resource

fhir-server-sharedservices: Miscellaneous services for FHIR resources

We acknowledge that this project does not handle security or logging.

  1. Incoming HTTP Requests

As we learned from the other platforms, you need to handle the incoming requests: validate the request, route, and return the response.

This is handled by the Program.cs/Main in fhir-server-CSharp (the entry point for our project)

This class also implements the routers for each resource type.

  1. REST Semantics and Parameter validation

REST semantics are handled for each resource by the {{ResourceClass}}SearchParameterValidation.cs class.

This includes

  1. Capability Statement

There is no simple way or library to calculate the capabilities of the FHIR Server, so we create the metadata response manually in a specific route (CapabilityStatement_Route method)

To cover the main functionalities of a server, we will focus on seeing how we incorporate the different resources that we want our server to handle and what operations on them we admit

We will look at the handling of exceptions, resource validation, legacy access and mapping.

Let's begin!

Steps to Create a C# RESTful Facade (using our example project)

These steps apply to a new resource or if you just need to review an existing resource implementation.

1- Create the Parameter Validation class

{{ResourceClass}}SearchParameterValidation.cs class.

2- Create the route inside of the main program.cs

{{ResourceClass}}_Route method

3- Add the resource to the valid resources. Review the method: IsResourceAllowedInThisServer(HttpListenerRequest request, out string resource)

4- Review the {{ResourceClass}}DataAccess.cs in the fhir-server-dataaccess project

This class implements access to the entities in the LegacyAPI. You can use them to add specific filters.

They only include three methods (GetAll, Get{{Resource}}). These methods return all the entities or the entities filtered by a specific search criteria.

5- Create the Mappers for the Resource and the Resource Bundle inside of the fhir-server-mapping project

Map{{ResourceClass}}.cs class.

Map{{ResourceClass}}Bundle.cs class.

6- Incorporate the resource, search parameters and interactions in the CapabilityStatement

Edit the CapabilityStatement_route method

The read operation retrieves a resource by ID. This is implemented in the fhir-server-dataaccess project using the id as a criteria for the search, and using a flag to return just the resource, and not the Bundle.

The search operation returns a Bundle with zero or many resources, which matches a given set of parameters.

A search is a very powerful and potentially very complicated operation to implement, with many possible parameters and combinations

In general, we can differentiate two types of searches – the first without parameters and the second with parameters.

The following example shows a search without parameters

We implement this operation using the GetAll method in the {{ResourceClass}}DataAccess.cs of the fhir-server-dataaccess project

To allow searches using parameters, add one or more parameters to your criteria parameter. It only requires the search parameter and the value. The parameters are enumerated in the LegacyFilter class in the fhir-server-model project

Within RESTful operations, it will generally return resources or bundles, but it will also have to return the errors to the client for various reasons.

To incorporate operation outcome and errors there is a utility method called getErrorOperationOutcome. It is used in combination with the HTTPStatusCode

Program.HttpStatusCodeForResponse = (int)HttpStatusCode.BadRequest;
oo = Utilz.getErrorOperationOutcome($"Unknown search parameter \"{param}\". Value search parameters for this search are: [_id, birthdate, email, telecom, family, gender, name, identifier]");

This week we will have formal "programming" assignments

We will ask you to change or enhance some of the features of our C# FHIR server.

FHIR is "just" a specification

In order to do real work, we need to use our desired libraries to enable access for our servers (facade)

We tried with this unit that you grasped common concepts that apply to all FHIR servers and then apply them to the most used platforms / languages (Java, C#, JS)

Information about FHIR

There are a number of places where you can get information about FHIR

Page