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.

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

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`	Stable	Mature
`ValueSet`	Mature	Mature
`ConceptMap`	Immature	Mature

Operation	Implementation
`/CodeSystem/$lookup`	Stable
`/ValueSet/$expand`	Mature
`/ValueSet/$validate-code`	Stable
`/ConceptMap/$translate`	Immature
`/ConceptMap/$closure`	Stable
`/$validate`	Stable
`/$batch`	Stable

Code System

Ontoserver supports the $lookup operations for both explicit and implicit code systems.

Lookup Operation

A lookup on a code within a given code system can be done using a GET or POST request such as:

http://ontoserver.base.url/fhir/CodeSystem/$lookup

where the code and system to lookup must be provided in the parameters of a GET request, or the body of a POST request.

The $lookup operation is supported according to its definition in the FHIR® Specification, and supports the code, system, version and coding parameters. The date and property parameters are not currently supported.

Successful lookups on SNOMED codes will include designations for fully specified names and synonyms, as well as properties for any parents or children.

Explicit Code Systems

Explicit Code Systems support SCRUD (Search, Create, Read, Update and Delete) operations as per the FHIR® Specification rules for REST and CodeSystems.

Search for explicit code systems is limited to the following parameters:

the name, id, description parameters (these 3 additionally support the :exact, :contains and :missing modifiers
the url and system parameters, including the :missing, :above and :below modifiers, and
the identifier and version parameters, including code, |code, system| and system|code formats

Implicit SNOMED CT Code Systems

Any SNOMED CT ontologies included in the Ontoserver instance are available as implicit CodeSystem resources, using a url of the format:

http://snomed.info/sct[/edition[/version]] where edition refers to the SNOMED CT module (e.g. SNOMED CT-AU) and version refers to the module’s version. More details can be found in the SNOMED CT URI Standard.

For example, the 20151130 version of SNOMED CT-AU has the url:

http://snomed.info/sct/32506021000036107/version/20151130

Value Set

Ontoserver supports the $expand and $validate-code operations for both explicit and implicit value sets.

Expand

A ValueSet resource can be expanded using a GET or POST request to a URL such as:

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

http://ontoserver.base.url/fhir/ValueSet/$expand (type-level)

The value set to be expanded in a type-level request is identified by the identifier parameter. Potential values for this parameter are explained in detail in the following sections. A value set expansion can also be controlled using the following parameters:

Parameter	Type	Description
filter	string	A text filter that is applied to restrict the codes that are returned (this is useful in a UI context). Ontoserver implements a multi-prefix match scoring algorithm.
count	integer	Paging support - where to start if a subset is desired (default = 0). This refers to items, not pages, i.e. offset = 2 means that the second matching record will be returned, not the second page.
offset	integer	Paging support - how many codes should be provided in a partial view. If count = 0, the client is asking how large the expansion is.

More details on the expand operation can be found in the FHIR® value set specification.

Validate Code

The validate-code operation checks whether a given code is valid within a given ValueSet resource. This is done by sending a GET or POST request to:

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

http://ontoserver.base.url/fhir/ValueSet/$validate-code (type level)

The ValueSet for a type-level request is specified using the identifier parameter. The code or coding is specified as a parameter to a GET request, or in the body of a POST request.

More details on the validate-code operation can be found in the FHIR® value set specification.

Explicit Value Sets

Explicit Value Sets in Ontoserver support SCRUD (Search, Create, Read, Update and Delete) operations as per the FHIR® Specification rules for REST and ValueSets.

Search for explicit value sets is limited to the following parameters:

the name, id, description parameters (these 3 additionally support the :exact, :contains and :missing modifiers
the url parameter, including the :missing, :above and :below modifiers, and
the identifier and version parameters, including code, |code, system| and system|code formats

Implicit Value Sets

Ontoserver supports two kinds of implicit value sets: implicit value sets for FHIR Code Systems, and implicit value sets for SNOMED CT resources.

Code System implicit value sets

Each explicit Code System resource has a corresponding implicit value set, which includes all concepts in the code system.

The url for the Code System’s implicit Value Set is defined in the Code System’s valueSet property if it is provided, or the Code System’s url property otherwise.

SNOMED CT Implicit Value Sets

When populated with Systematized Nomenclature of Medicine - Clinical Terms (SNOMED CT) terminology, Ontoserver exposes a number of implicit value sets according to the FHIR specification. These include implicit value sets for reference sets and by subsumption.

A SNOMED CT value set is technically identified by a URL. This URL has two parts: a base part that identifies the SNOMED CT edition and version, and a query part that specifies the scope of the value set’s content.

Base Part

The base part of the URL has the format, http://snomed.info/sct[/edition[/version]] where edition refers to the SNOMED CT module (e.g. SNOMED CT-AU) and version refers to the module’s version. More details can be found in the SNOMED CT URI Standard.

E.g. http://snomed.info/sct/32506021000036107/version/20151130

If an edition is specified with no version, then the server will look for the latest version of the edition that is available. If no edition or version are specified then the server will look for the latest version of a preconfigured edition, which is specific to each FHIR® server. The default edition in the National Terminology Server (NTS) is SNOMED CT-AU.

Query Part

The query part of the URL determines the type of value set. Two types of value sets are supported by the NTS: those based on reference sets and those based on subsumption.

Based on Reference Sets

The query part of the URL for value sets based on reference sets has the format,

?fhir_vs=refset/[sctid]

where sctId is the concept id of a reference set.

The list of reference sets available for an edition is also available as an implicit value set with URL,

http://snomed.info/sct[/edition[/version]]?fhir_vs=refset

Based on Subsumption

The query part of the URL for value sets based on subsumption has the format,

?fhir_vs=isa/[sctid]

where sctId is the concept id of any SNOMED CT concept in the specified edition.

Concept Map

Ontoserver supports the $translate and $closure operations for ConceptMaps.

Concept Maps support SCRUD (Search, Create, Read, Update and Delete) operations as per the FHIR® Specification rules for REST and ConceptMaps.

Search for concept maps is limited to the following parameters:

the name, id, description parameters (these 3 additionally support the :exact, :contains and :missing modifiers
the url parameter, including the :missing, :above and :below modifiers, and
the identifier and version parameters, including code, |code, system| and system|code formats

Translate

The translate operation shows how a code in one value set relates to codes in another according to known concept maps. It can be invoked using a GET or POST request to

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

http://ontoserver.base.url/fhir/ConceptMap/$translate (type level)

The code and the source/target value sets are specified either as parameters to a GET request, or in the body of a POST request.

More details about the translate operation can be found in the FHIR® Specification.

Closure

The closure operation allows for ongoing maintenance of client-side closure tables for a set of codes, represented as a ConceptMap. The operation can be accessed by sending a GET or POST request to

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

The name of the client’s closure table, and any concepts to add to it, are provided as parameters to a GET request, or in the body of a POST request.

More details on the closure operation can be found in the FHIR® Specification.

Data Formats

The FHIR® specification 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/json+fhir;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 operations ($lookup, $expand, $validate-code, $translate, $closure), Ontoserver supports two generic operations: $validate and $batch.

Validate

The validate operation checks a resource’s well-formedness against its schema, constraint rules, and any profiles to which it claims to conform. 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). Type level requests can specify which resource to validate by id in a parameter of a GET request, or in the body of a POST request.

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.

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 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.

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

Other operations

Note that even though the server implements some additional operations in the FHIR® specification, these are not officially supported and therefore their use is discouraged. Any results obtained from unsupported operations are untested and not guaranteed to be valid.

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.