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, and Bundle.
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 | Mature |
| ValueSet | Mature | Mature |
| ConceptMap | Stable | Mature |
| Bundle | Mature | Immature |
| StructureDefinition | Mature | Immature |
| Operation | Implementation |
|---|---|
| /CodeSystem/$lookup | Mature |
| /CodeSystem/$subsumes | Stable |
| /CodeSystem/$validate-code | Stable |
| /ValueSet/$expand | Mature |
| /ValueSet/$validate-code | Mature |
| /ConceptMap/$translate | Mature |
| /ConceptMap/$closure | Stable |
| [ResourceType]/$validate [ResourceType]/[id]/$validate |
Stable |
| /$batch | 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 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 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.
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:
| 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.