5. NRL Stub API - nhsconnect/nrls-reference-implementation GitHub Wiki

An API written in C# using Visual Studio 2017. Any IDE capable of developing with .NET Core v2.0 can be used.

In this section:

5.1 Framework

.NET Core

The framework in use is .NET Core v2.0.

Along with the more advanced features that this framework provides it also takes care of some boilerplate code that we previously had to write and re-write ourselves such as dependency injection.

FHIR

To help manage FHIR related resources and web request we are utilising the Hl7.Fhir.STU3 package from ewoutkramer.

5.2 Configuration

There is a single configuration file, app settings.

AppSettings

The most important settings:

  • NRLSMongoDB
    This contains the datastore connection string config

  • NRLSAPI
    This contains default values for endpoints, ports, security and constraints around allowed FHIR resources, content types, and profiles.

  • Spine
    For the fake spine middleware these options provide the defaults. See below for more details.

  • SSP
    This contains default values for endpoints, ports, and security.

Environments

It is possible to define environment specific configs which will override any settings defined in them.

The convention is [config file name].[environment].json

 

5.3 Structure

The structure is simple, the following make up the important areas:

  • WebApp
  • Services
  • Database

The other projects provide a supporting role for these.

5.3.1 Entry Points

There is one entry point to the API, the NRLS-API.WebApp, which has four main roles:

  • NRL Stub Controller
  • PDS Stub Controller
  • ODS Stub Controller
  • SSP Stub Controller

NRL Stub

This is the main web API interface used by the Demonstrator and is also externally available to test against.

Example endpoint:

GET http://[BaseUrl]/nrls/fhir/DocumentReference?[search parameters]

PDS Stub

This is the main web API interface used by the Demonstrator to get patients.

Example endpoint:

GET http://[BaseUrl]/pds/fhir/Patient/[id]

ODS Stub

This is the main web API interface used by the Demonstrator to get organisations.

Example endpoint:

GET http://[BaseUrl]/ods/fhir/Organization/[id]

SSP Stub

This is the main web API interface used by the Demonstrator to get patient records from a provider endpoint (found in the Demonstrator.WebApp controllers).

Example endpoint:

GET http://[BaseUrl]/ssp/[provider-record-url encoded]

5.3.2 SPINE Middleware and Security

To help mimic the SPINE there is some middleware files located in the NRLS-API/WebApp/Core/Middlewares folder.

The main roles here are to inspect and validate the following:

  • Headers
  • JWT
  • SSL Certificate

ASIDs

ASIDs are checked against the SDS data stored in the data layer.

This data collection contains entries that map ASIDs to the associated SSL Thumbprint, organisation ODS code, allowed interaction IDs, and registered endpoints.

Provider Interactions

When performing provider interactions the ASID and other details are checked against the incoming request to create a Pointer or update/delete a Pointer to ensure that the ASID used matches the Custodian ODS code stored on the Pointer.

5.3.3 Services

The services are split into 4 main sections:

  • FHIR Services
    These are the core services for all end points and deal with both query and maintenance calls.

  • NRL Services
    These are custom methods that sit between the NRL Controller and the FHIR Services and are to add NRL specific layers of logic above the base FHIR logic before moving on down to the FHIR Services.

  • FHIR Validation
    These services hold the entry points to both fhir validation and NRLS/NHS specific validation.

    This is backed by the Validation Helper class.

  • Supporting Services
    These services include PDS, ODS, SDS, and SSP and contain layers of logic specific to those resource types.

5.3.4 Validation

As detailed above there are a number of layers to validation:

  • Spine/SSP Middleware
  • FHIR Validation

5.3.4.1 Content Types

There is also in place a FHIR JSON and FHIR XML middleware setup to allow for the acceptable contents types.

Due to specific error response rules required by the NRL the middleware will only try to parse incoming messages as base FHIR JSON and FHIR XML resources. These are then forwarded to the Validation Services to allow for specific rules to be run and errors to be extracted in a controlled way.

5.3.4.2 Easy Validation

The Pointers sent in to the NRL are validated against the NRL Document Reference Profile using the built in FHIR Validation that comes with the HL7.Fhir.STU3 package for easy validation.

There are a few additional steps of validation performed that the FHIR Validator does not check.

5.3.5 Data Store

This is a standard installation of MongoDB and uses the official MongoDB driver for all interactions between the services and the data store.

The AppSettings configuration allows you to configure where the DB is located and what credentials and default database is used.

5.4 Build

The build procedure is as standard across a .NET application. Running your IDE build commands will suffice.

5.4.1 Deploy Pipeline

As a standard build this can be integrated into a standard deploy pipeline.

For this project we are using Docker and so is built as part of the Image build. Details can be found in the Deployment section.