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) | Mature |
Bundle |
Mature (N) | Mature |
StructureDefinition |
Mature (N) | Mature |
NamingSystem |
Immature (1) | Mature |
Operation | Specification | Implementation |
---|---|---|
/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:
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.