Technical overview
This document contains the following sections:
- Calling the API
- Access to the API
- Search
- Data update cycle
- SAFEST & FEST
- Data to be delivered in the API
- Simple code example
Calling the API
The API can be accessed at https://api.legemiddelverket.no/fhir-r4 and follows the API specification defined in the FHIR standard. The resources can be fetched through the following pattern:
GET api.legemiddelverket.no/fhir-r4/[delta?]/[resourceType]/[id?]/[_history?]
Where the allowed resource types are:
- MedicinalProduct
- MedicinalProductPackaged
- MedicinalProductManufactured
- CodeSystem
If delta is included the incemental Delta API is called, otherwise the snapshot is used (see Data update cycle). The Delta API provides the option to include all previous versions of the resources through the _history option.
If an id is provided, a specific resource is returned - if not, a list of entities are returned allowing one to fetch all entities of a given type.
Note that the API only provides read access to each resource.
Access to the API
For access to the API, send a request to NoMA with the following information:
- Organization name
- Contact person (Name / E-mail)
Any organisation with access to the API is required to inform NoMA on changes to the contact person.
After access has been granted by NoMA, the API may be access by provided in the API Key in the header through "Ocp-Apim-Subscription-Key".
Search
The API provides resource searching according to the Azure API for FHIR search functionality: https://docs.microsoft.com/en-us/azure/healthcare-apis/azure-api-for-fhir/overview-of-search.
The resources available for searching are:
MedicinalProduct
MedicinalProductManufactured
MedicinalProductPackaged
The API also includes custom search parameters to search for product codes on MedicinalProductPackaged.
As the packageItem element in practice can only have three levels, three custom search parameters have been defined in order to search for product codes on each level.
- package-item-level-one
- package-item-level-two
- package-item-level-three
Examples
Search for specific Medicinal Product using SafestMedicinalProductID:
GET https://api.legemiddelverket.no/fhir-r4/MedicinalProduct/161779346577762818209490948038614807285
Search for Medicinal Product Packaged with nordicArticleNumber:
GET https://api.legemiddelverket.no/fhir-r4/MedicinalProductPackaged?identifier=801773
Search (all three levels) for Medicinal Product Packaged with product code:
GET https://api.legemiddelverket.no/fhir-r4/MedicinalProductPackaged?package-item-level-one=05415062316955
GET https://api.legemiddelverket.no/fhir-r4/MedicinalProductPackaged?package-item-level-two=05415062316955
GET https://api.legemiddelverket.no/fhir-r4/MedicinalProductPackaged?package-item-level-three=05415062316955
Data update cycle
The update cycle for NoMA's FHIR API is aligned with FEST and data is thus refreshed twice per month. The updated datas can be found on NoMA's website.
Every update will have one full dataset, called snapshot. This endpoint provides only the latest version of all active resources.
- The current snapshot is found at https://api.legemiddelverket.no/fhir-r4
There will also be an incremental dataset, called delta. This endpoint will be updated incrementally with resources which have been updated since the last snapshot was published. It contains the version history for all resources ever published.
- The incremental updates are found at https://api.legemiddelverket.no/fhir-r4/delta.
SAFEST & FEST
FEST is currently the primary source of quality assured, structured medicine master data in Norway.
For the years to come, both FEST and SAFEST will co-exist, which requires the consumers to be able to map, convert and reference between the two. Therefore, providing complete integrity between the two master data sources is of the utmost importance. The following measures to ensure SAFEST – FEST integrity are in place:
- Synchronized release schedule. Both FEST and SAFEST are generated, compiled and released on the same date and based on the same underlying data.
- References across SAFEST and FEST: SAFEST contains references to the corresponding data elements in FEST (legemiddelMerkevareID, legemiddelDoseID and Nordic Article Number). For details, see the profiles documentation
- Automated integrity tests executed at every release
Data to be delivered in the API
NoMA's FHIR API only carries the subsection of medicinal and nutrional products which are relevant for the Regional Health Authorities.
The filtering rules used to determine which data is not included in NoMA's FHIR API are described below.
ATC code
If the ATC code of a medicinal product starts with "Q", the medicinal product and all connected packages are excluded.
Preparation type
If the preparation type (Preparattype) is Homeopathy human ("Homøopatisk human") or Homeopathy veterinary ("Homøopatisk veterinær") the medicinal product and all connected packages are excluded.
Marketing status
If a package has not been marketed within the last three months, it will be removed.
Nordic Article Number
If a package doesn't have a Nordic Article Number, it is excluded.
If a package has a Nordic Article Number that has been expired for more than 3 months, it is excluded.
Start- and combination package
If a package is a start- or combination package, it is excluded.
Legemiddeldose
If a Legemiddeldose has an expiration date, it is excluded.
Simple code example
This section provides a simple code example for using the FHIR API based on the HL7.FHIR package available in C#/.NET. First, in order to call the API one needs to be able to add headers to the client. This is done by creating a custom HttpClientHandler:
public class HeaderHandler : HttpClientHandler
{
public string headerName { get; set; }
public string headerValue { get; set; }
protected async override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
{
if (headerName != null && headerValue != null)
{
request.Headers.Add(headerName, headerValue);
}
return await base.SendAsync(request, cancellationToken);
}
}
The API can now be called with the following:
using Hl7.Fhir.Model;
using Hl7.Fhir.Rest;
using System.Configuration;
// Setup settings
string _subscriptionKey = ConfigurationManager.AppSettings["subscriptionKey"] ?? ""; // TODO: Add key to App.config
var demoId = "MedicinalProduct/{TODO: INSERT YOUR ID HERE}";
var fhirUrl = "https://st-api.legemiddelverket.no/fhir-r4";
// Initiate the FHIR Client.
var settings = new FhirClientSettings()
{
PreferredFormat = ResourceFormat.Json
};
// Note: A custom header is added for authentication purposes.
var handler = new HeaderHandler
{
headerName = "Ocp-Apim-Subscription-Key",
headerValue = _subscriptionKey
};
var client = new FhirClient(fhirUrl, settings, handler);
// The client can now be used to fetch a given resource.
var medicinalProduct = await client.ReadAsync<MedicinalProduct>(demoId);