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:

This section is quite long. Use the mouse wheel to scroll!

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:

• R4 - use fhirVersion=4.0.1

• R4B - use fhirVersion=4.3.0

• R5 - use fhirVersion=5.0.0

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 resource

• text -> return text, 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 the text element that contains a human-readable rendering of the resource, in the form of eg. an XHTML snippet

• count -> 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:

CodeSystemValueSetConceptMap

Resource 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:

HTTP Status	Reason
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>