FHIR®🔥 API

This page describes the parts of the Fast Healthcare Interoperability Resources (FHIR®) specification that are implemented by Ontoserver. These may be accessed programmatically using the FHIR REST API for Search, Create, Read, Update, and Delete (SCRUD) interactions.

Ontoserver supports the following Resource Types: CodeSystem, ValueSet, ConceptMap, StructureDefinition, Bundle and NamingSystem.

FHIR Versions

Ontoserver implements FHIR R4. Ontoserver also provides limited support for STU3. Specifically, when providing application/fhir+json or application/fhir+xml content to Ontoserver, the optional MIME-type parameter fhirVersion can be included in the Content-Type header (as per the specification's FHIR Version Parameter). In this case, Ontoserver will attempt to auto-convert the resource to R4 before handling the request.

Maturity Model

The different parts of the FHIR API implemented by Ontoserver are at different levels of maturity. These are indicated in the table below. The maturity levels are:

  • (Mature): These features are stable in the specification and their implementations in Ontoserver have been exposed to significant use and testing.

  • (Stable): These features are stable in the specification. Although their implementations have been tested, some minor issues may be found.

  • (Immature): These features are subject to some change in the specification and/or their implementation in Ontoserver. They are appropriate for trial use only.

Resource Specification SCRUD Operations
(Search/Create/Read/Update/Delete)
CodeSystem Mature (N) Mature
ValueSet Mature (N) Mature
ConceptMap Stable (3)
(Significant changes slated for R5)
Mature
Bundle Mature (N) Mature
StructureDefinition Mature (N) Mature
NamingSystem Immature (1) Mature
Operation Specification Implementation
/CodeSystem/$find-matches Immature (0) Immature
/CodeSystem/$lookup Mature (N) Mature
/CodeSystem/$subsumes Mature (N) Mature
/CodeSystem/$validate-code Mature (N) Stable
/ValueSet/$expand Mature (N) Mature
/ValueSet/$validate-code Mature (N) Mature
/ConceptMap/$translate Stable (3) Mature
/ConceptMap/$closure Stable (3) Stable
/NamingSystem/$preferred-id Immature (1) Stable
/[Resource]/[id]/$meta
/[Resource]/[id]/$meta-add
/[Resource]/[id]/$meta-delete
Stable (3) Stable
(persisted resources only)
/[Resource]/$validate
/[Resource]/[id]/$validate
Mature (N) Stable
(any resource type)
/$convert Immature (1) Stable
/$batch Mature (N) Stable
/$versions Mature (5) Stable

Data Formats

Ontoserver supports both XML and JSON. There are several ways to ask the server to return the content using a specific format. The simplest way is to include the parameter _format in the URL. For example, to request the content in XML the parameter _format=xml can be used.

By default, if no format is specified, the server will return JSON using the UTF-8 character encoding (Content-Type = application/fhir+json;charset=utf-8).

More details about alternative ways of requesting content in a specific format can be found in the data format section of the FHIR specification.

Supported Operations

In addition to the above resource-specific operations ($lookup, $expand, $validate-code, $translate, $closure, $preferred-id), Ontoserver supports a number of more general operations: $validate, $convert, $batch, and $versions, as well as $meta, $meta-add, and $meta-delete.

Validate

The validate operation checks a resource's well-formedness against its schema, constraint rules, and against one or more profiles.

The operation can be invoked by sending a GET or POST request to:

http://ontoserver.base.url/fhir/[ResourceType]/[id]/$validate (instance level)

http://ontoserver.base.url/fhir/[ResourceType]/$validate (type level)

Where [ResourceType] is one of Ontoserver's supported Resource Types (ValueSet, CodeSystem, ConceptMap) or, if ontoserver.feature.generic-validation-enabled is set to true, type-level invocation for all FHIR Resource Types. Type-level requests can provide a resource to validate as a JSON/XML object in the body of a POST request.

If the profile parameter is provided, the resource will be validated against the most recent stored StructureDefinition with that URL. Otherwise, it will be validated against any profiles to which it claims to conform (in its meta section), or against the default profile for that resource type.

If a referenced StructureDefinition is not available locally, Ontoserver will look in the syndication feeds, if any, configured using atom.validation.feedLocation for the appropriate Resource. If found, the StructureDefinition will be fetched and used for the purposes of validation, but will not be automatically loaded into Ontoserver itself.

The operation returns a list of any issues with the resource, as well as their seriousness.

More information on the validate operation can be found in the FHIR specification.

Convert

The convert operation takes a resource in one form, and returns to in another form. Both input and output are a single resource. The primary use of this operation is to convert between formats (e.g. (XML -> JSON or vice versa).

Ontoserver also supports converting FROM FHIR STU3 TO FHIR R4. This is done by specifying the FHIR version in the Content-type header. For example: Content-type: application/fhir+json; fhirVersion=3.0

The operation can be invoked by sending a POST request to:

http://ontoserver.base.url/fhir/$convert

More information on the validate operation can be found in the FHIR specification.

Batch

The batch operation allows for the invocation of a series of operations in a single call. Batch operations can be performed by sending a Bundle object, encoded as either JSON or XML (with an appropriate Content-Type header), of type batch, in a POST request to the FHIR base, i.e.

http://ontoserver.base.url/fhir

The operations supported in batch operations are: $expand, $lookup, $translate, $validate-code and $subsumes.

Each bundle entry in the batch request must specify a request method and url. GET entries may specify parameters in their URL; POST entries may specify parameters by providing a Parameters object in the resource parameter of the bundle entry.

Results from a batch request will be provided as a bundle object, with the results for individual requests in the same order as the request entries.

More information about the batch operation can be found in the FHIR Specification.

Versions

The result of this operation identifies the set of FHIR versions supported by Ontoserver along with the default FHIR version.

The operation can be invoked by sending a GET request to:

http://ontoserver.base.url/fhir/$versions

Meta

  • $meta Returns a list of all profiles, tags, and security labels for the current version of the resource. Also, as a special case, this operation (and other meta operations) can be performed on a historical version of a resource). More information can be found in the FHIR Specification

  • $meta-add This operation takes a meta, and adds the profiles, tags, and security labels found in it to the nominated resource. More information can be found in the FHIR Specification

  • $meta-delete This operation takes a meta, and deletes the profiles, tags, and security labels found in it from the nominated resource. More information can be found in the FHIR Specification

Error Codes

A number of error codes are possible in response to requests to Ontoserver FHIR endpoints. These include:

Error Codes
HTTP Status Code Reason
400 Bad Request
401 Unauthorised. Log into the FHIR endpoint.
403 Not authorized. The user does not have sufficient permissions for the provided request.
404 Not Found. The specified resource cannot be found or the reference set id is invalid.
422 Unprocessable Entity. The resource provided is not well-formed.
500 An internal error has occurred

Examples

For examples of FHIR requests, see the Postman link in the left pane.

This link provides a collection of Postman requests for the FHIR endpoints, that can be sent to an Ontoserver (or other FHIR Terminology service) installation.