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
/CodeSystem/$subsumes Immature
/ValueSet/$expand Mature
/ValueSet/$validate-code Stable
/ConceptMap/$translate Immature
/ConceptMap/$closure Stable
/$validate Stable
/$batch Stable

Code System

Ontoserver supports the $lookup and $subsumes 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 and property (including lang.X values) parameters. The date parameter is 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, and inactive status for inactive codes.

Subsumes Operation

Subsumes tests whether a given concept subsumes another concept. The subsumes operation can be invoked using a GET or POST request, at either the instance or type level, such as:

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

http://ontoserver.base.url/fhir/CodeSystem/$subsumes (type level)

where the codeA and codeB to compare must be provided in the parameters of a GET request, or the body of a POST request, or the codingA and codingB parameters in the body of a POST request. The code system for the codes in a type-level request is identified by the system parameter, and optionally the version parameter.

The $subsumes operation is supported according to its definition in the FHIR Specification, and supports the codeA, codeB, system, version, codingA, and codingB parameters.

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, version and _tag 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 20171031 version of SNOMED CT-AU has the url:

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

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 url parameter if using a GET-style request. Potential values for this parameter are explained in detail in the following sections.

Alternatively, if a type-level request is sent using POST, the value set to be expanded can be specified either using the url parameter in a Parameters object of the POST body, or as a JSON/XML resource, in the valueSet parameter of a Parameters object (if valueSet is the only parameter being provided to the expand request, the JSON/XML resource may be passed as the POST body without a surrounding Parameters object).

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.
activeOnly boolean Whether or not inactive concepts are included in the expansion (false by default)
includeDesignations boolean Whether or not concepts included in the expansion should also come with their designations (false by default)
includeDefinition boolean Whether or not to include the logical definition and metadata of the value set in the expansion (true by default

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 url parameter. In the case of a POST-style type-level request, the ValueSet may alternatively be provided as an XML/JSON resource in the valueSet parameter within a Parameters object.

The code (with a system and optionally a version) is specified as a parameter to a GET request, or in the body of a POST request (POST requests may alternatively provide a coding parameter. If a display parameter is provided, the operation will also verify whether the display is correct for the specified concept.

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, version and _tag 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/20171031

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.

The fixed URL for the implicit ValueSet of all SNOMED concepts is http://snomed.info/sct/fhir_vs. This may optionally include the edition and version (http://snomed.info/sct[/edition[/version]]?fhir_vs).

Ontoserver also supports implicit ValueSets based on reference sets, and 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.

LOINC Implicit Value Sets

When populated with LOINC terminology, Ontoserver exposes a number of implicit value sets according to the FHIR specification. These include implicit value sets for answer lists and multi-axial hierarchy entries.

The code system URL for LOINC is http://loinc.org.

The implicit ValueSet URL for all LOINC terms is http://loinc.org/vs.

The implicit ValueSet URL for a LOINC answer list is http://loinc.org/vs/[answer-list-code].

The implicit ValueSet URL for the LOINC multi-axial hierarchy given by a LOINC part code is http://loinc.org/vs/[part-code].

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, source-system,target-system, source-uri and target-uri parameters, including the :missing, :above and :below modifiers, and

  • the identifier, version, source-code, target-code and _tag 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, system and optional version (or alternatively a coding in a POST request) of the concept to be translated, as well the source & target value sets, are specified either as parameters to a GET request, or within a Parameters resource in the body of a POST request. The translation can be run in reverse by setting the optional reverse parameter to true.

Instance-level invocations work using the explicit ConceptMap with the given id. Type-level invocations that specify the url parameter work using the explicit or implicit ConceptMap corresponding to that url.

Type-level invocations can provide a url to reference an explicit ConceptMap, an implicit ConceptMap, or an algorithmic ConceptMap.

Type-level invocations that do not provide a url invoke a default mapping feature, which makes a best attempt to match the code, coding or CodeableConcept, based on whatever text is available (codes, descriptions, synonyms, etc).

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 is provided as a parameter to a GET request, or in the body of a POST request.

The first call to $closure with a given name will create an empty closure table.

Subsequent requests may specify one or more concepts to add to the table as codings using the concept parameter; the result of such a request will be a ConceptMap including the list of new subsumption relationships that result from the addition of the concepts. Requests may see the complete list of subsumption relationships in the closure table by passing a version parameter with value 0 (inspecting intermediate versions of the closure table is not currently supported).

More details on the closure operation can be found in the FHIR® Specification, and its section on Closure Table maintenance.

Implicit Concept Maps

Ontoserver supports implicit concept maps for the following SNOMED historical association reference sets, with the corresponding URLs, as per the FHIR Specification.

  • Possibly Equivalent To : http://snomed.info/sct[/edition[/version]]?fhir_cm=900000000000523009

  • Replaced By : http://snomed.info/sct[/edition[/version]]?fhir_cm=900000000000526001

  • Same As : http://snomed.info/sct[/edition[/version]]?fhir_cm=900000000000527005

  • Alternative : http://snomed.info/sct[/edition[/version]]?fhir_cm=900000000000530003

These concept maps can be used by providing the implicit ConceptMap URLs as the URL parameter to a type-level invocation of the $translate operation.

Algorithmic Concept Maps

Ontoserver supports the following algorithmic concept maps:

  • http://ontoserver.csiro.au/profiles/automapstrategy/default
    Ontoserver’s default automapping strategy. This extracts the display text from supplied Coding and CodeableConcept items (no code or system required) and attempts to find the best match in the target ValueSet. It does not require all words to match, and also attempts simple spelling correction. It is designed for reasonably well-formed textual input, and is not suitable for arbitrary free text.

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 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 provide a resource to validate as a JSON/XML object 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, 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.

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.