FHIR API
Introduction
HL7's Fast Healthcare Interoperability Resources (FHIR) standard describes data types, resources, interactions, coded values and their associated code systems that are used to represent and exchange structured clinical data.
Thanks to its pluggable and extensible architecture, Snow Owl TS is able to expose clinically relevant resources like code systems, value sets and concept maps in a format that can be consumed by third-party FHIR clients. Additionally, Snow Owl's revision model allows concurrent management of resource versions.
Interactive documentation
Navigate to http://<host>:8080/snowowl/
and select "FHIR API" from the category dropdown to see the full list of FHIR requests supported by Snow Owl TS:

We also provide a Postman collection with pre-populated example requests to try: https://documenter.getpostman.com/view/16295366/2s93z3h6cP
Request/response formats
JSON and XML formats are both supported; resources in Turtle RDF format are not accepted (nor produced) by the server. The MIME type for these formats can appear in the Accept
and Content-Type
headers. These are the following:
XML
application/fhir+xml
application/xml
text/xml
JSON
application/fhir+json
application/json
text/json
Unless explicitly stated in the MIME type, the server accepts and responds in the R5
format. To select an explicit FHIR version format the fhirVersion
argument can be used along with the fhir+json/xml
media types. For example:
Accept: application/fhir+json;fhirVersion=4.0.1
All declared and provided FHIR endpoints support the following FHIR Specification versions:
Common request parameters
Override response format
Clients can override the desired output format by using the _format
query parameter, if they have limited access to request headers. In this case shorthand values like xml
and json
are also permitted (Content-Type
must still be set correctly if the request includes a body):
GET /snowowl/fhir/CodeSystem/SNOMEDCT?_format=xml&_pretty=true
[Response headers]
Content-Type: application/fhir+xml
<CodeSystem xmlns="http://hl7.org/fhir">
<id value="SNOMEDCT"/>
<meta>
<lastUpdated value="2023-10-17T15:03:40.942Z"/>
</meta>
<language value="en"/>
<text>
<status value="empty"/>
<div xmlns="http://www.w3.org/1999/xhtml"></div>
</text>
<url value="http://snomed.info/sct/900000000000207008"/>
<name value="SNOMEDCT"/>
<title value="SNOMED CT International Edition"/>
<status value="active"/>
[...]
Snow Owl returns a 406 Not Acceptable
response if the client requested a response format it does not support. Conversely, if the request body is in a format it does not recognize, a 415 Unsupported Media Type
response is emitted.
Pretty-printing
For development purposes, responses returned from the server can be formatted so they are more pleasing to the human eye. The example above already includes the query parameter that controls this behavior; it is named _pretty
. Setting its value to true
results in pretty-printed output.
Resource summary
The query parameter _summary
controls whether a subset of the elements should be returned for a resource. Supported values are:
true
-> return a pre-defined subset of elements from the resource (these are marked as "summary" in the FHIR specification)false
-> return all elements of the resourcetext
-> returntext
,id
,meta
and top-level elements marked as "mandatory" in the FHIR specification (to ensure that the response remains a valid FHIR resource representation)data
-> remove thetext
element that contains a human-readable rendering of the resource, in the form of eg. an XHTML snippetcount
-> return hit count without the accompanying list of matching resources (applicable in resource search interactions only)
When summary mode is enabled, returned resources are marked with a SUBSETTED
code to indicate that certain elements were left out:
GET /snowowl/fhir/CodeSystem/SNOMEDCT?_summary=text
[Response headers]
Content-Type: application/fhir+json
{
"resourceType": "CodeSystem",
"id": "SNOMEDCT",
"meta": {
"lastUpdated": "2023-10-17T15:03:40.942Z",
"tag": [{
"system": "http://terminology.hl7.org/CodeSystem/v3-ObservationValue",
"code": "SUBSETTED",
"display": "As requested, resource is not fully detailed."
}]
},
"text": {
"status": "empty",
"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"></div>"
},
"status": "active",
"content": "not-present"
}
Element selection
If none of the _summary
modes listed above are appropriate for a use case, clients can select individual elements for inclusion via the _elements
query parameter. Its value should be a comma-separated list of element names. Elements marked as "mandatory" are always returned.
As above, the returned resource's meta.tag
element will also include a SUBSETTED
Coding to indicate that some information has been left out.
Sorting and paging
Clients can indicate the preferred number of results to return on a single page via the _count
query parameter. Paging via offsets is not supported, but the response usually includes a link of type "next" to retrieve the next page:
GET /snowowl/fhir/CodeSystem?_count=5
[Response headers]
Content-Type: application/fhir+json
{
"resourceType": "Bundle",
"id": "codesystems",
"meta": {
"lastUpdated": "2023-11-28T18:37:52.057338Z"
},
"type": "searchset",
"link": [{
"relation": "next",
"url": "https://<host>/snowowl/fhir/CodeSystem?_count=5&_after=AoIhMDg2dlE2dHd4YkRDNnZHWjUxNGYzWlplR2M="
}],
"total": 1676,
"entry": [
{
"fullUrl": "https://<host>/snowowl/fhir/CodeSystem/resource_1",
"resource": {
"resourceType": "CodeSystem",
"id": "resource_1",
"meta": {
"lastUpdated": "2023-10-19T13:21:52.216Z"
},
"name": "resource_1",
"title": "First resource",
...
}
},
...
]
}
As can be seen from the example, the paging mechanism uses an additional state tracking parameter called _after
.
Resource types
Snow Owl only supports a small subset of FHIR's 150+ resource types – the ones that are relevant from a terminology service perspective. These are described on separate pages in detail:
CodeSystemValueSetConceptMapResource identifiers
The id element of each resource is assigned by Snow Owl in create interactions; the assigned value never changes once it has been set and is unique across resource types. Update interactions that use an identifier which did not exist previously will create a new resource – in this case the identifier is checked for potential collisions first.
Snow Owl represents versioned content as standalone resources when accessed via the FHIR API (the version part is separated from the resource identifiers by a /
character which is not allowed to be used in "regular" FHIR identifiers):
GET /snowowl/fhir/CodeSystem/SNOMEDCT/2021-01-31
[Response headers]
Content-Type: application/fhir+json
{
"resourceType": "CodeSystem",
"id": "SNOMEDCT/2021-01-31",
"meta": {
"lastUpdated": "2023-10-17T14:59:31.529Z"
},
"url": "http://snomed.info/sct/900000000000207008/version/20210131",
"version": "2021-01-31",
"name": "SNOMEDCT/2021-01-31",
"title": "SNOMED CT International Edition",
"status": "active",
"date": "2021-01-31T00:00:00Z",
"publisher": "SNOMED International",
"content": "not-present",
"count": 481509,
...
}
If there are no versions present for a given resource, or the requested identifier does not include a version part, the latest development version is returned which may include "in-progress" changes. Therefore it is recommended to always query a specific version of any terminology content to get consistent results, especially when the same terminology server instance is being used for both authoring and distribution.
Response status
The following HTTP status codes are used by Snow Owl's FHIR API to indicate the success or failure of an interaction:
200
OK
400
Bad Request
401
Unauthorized
403
Forbidden
404
Not Found
500
Internal Error
If an error occurs, a response containing an OperationOutcome
resource may be returned to include additional details about the problem at hand:
GET /snowowl/fhir/CodeSystem/abc
[Response headers]
Content-Type: application/fhir+xml
<OperationOutcome>
<resourceType>OperationOutcome</resourceType>
<issue>
<severity>error</severity>
<code>not_found</code>
<diagnostics>
Code System with identifier 'abc' could not be found.
</diagnostics>
<details>
<text>Resource Id 'abc' does not exist</text>
<coding>
<code>msg_no_exist</code>
<system>http://hl7.org/fhir/operation-outcome</system>
<display>Resource Id 'abc' does not exist</display>
</coding>
</details>
<location>abc</location>
</issue>
</OperationOutcome>
Last updated