201805 Versioned API

From HL7Wiki
Revision as of 07:07, 12 May 2018 by Kolbrich (talk | contribs)
Jump to navigation Jump to search

WIP -- Work in Progress

Track Name

Versioned API

Submitting WG/Project/Implementer Group


Proposed Track Lead

Kevin Olbrich See Connectathon_Track_Lead_Responsibilities

The Problem

Many server operators and clients have been implemented on a variety of FHIR versions. In order to facilitate supporting newer versions of FHIR, it is necessary to work out mechanisms by which multiple FHIR versions can be supported side-by-side. Otherwise we run the risk of locking both vendors and consumers into legacy versions of FHIR due to the operational difficulty of migrating.


Interest is growing in how to manage cross-version use of the FHIR API. This connectathon stream tests out 2 aspects of cross-version use of the FHIR API:

a single end-point that supports more than one version (Scenarios #1 and #2) how to handle changes a resource between versions (Scenarios #3 and #4)

Expected participants

Kevin Olbrich (McKesson)

Approaches to Versioning

URL versioning

The simplest approach to versioning is to include a version identifier in the URL of the FHIR server (e.g, `https://test.fhir.org/r4`). While this approach is easy to implement it suffers from several limitations. Assuming a consuming service stores a reference to a patient as `iss=https://test.fhir.org/r4 ref=Patient/123` then several problems arise. 1. The server operator needs to maintain that URL indefinitely or they run the risk of breaking consuming applications. 2. The URL makes promises about the version, so the server operator would need to ensure that the url continued to serve resources in the appropriate version 3. The client is also obligated to maintain the ability to read/write older versions of the FHIR standard as long as the record continues to point to the old version 4. The FHIR version of the Resource is not semantically meaningful for the most part. Consuming applications really are interested in references to a particular resource and the FHIR version is a detail that needs to be worked out for communication. 5. The sever operator needs to ensure that changes to a record are reflected in all supported versions, which may impose a high operational and support cost.

MIME-type negotiation

An alternative approach to server versioning that follows web-standard MIME-type negotiation.

In this approach the server operator inspects the incoming `Accept` header of a request and uses this to determine which version of FHIR to respond with. The `Accept` header should be formatted like `Accept: application/json+fhir;fhirVersion=3.0,application/fhir+json;fhirVersion=1.4;application/json` (and/or the xml equivalent, if desired). The FHIR version is specified by adding the `fhirVersion=X.X` parameter to the mime type, where `X.X` is the major.minor version of FHIR that is requested. (Patch level versions are generally considered to be unimportant for API changes and may be ignored by the server). The server operator should use the first specified type that they support.


Please include information here regarding how much advance preparation will be required if creating a client and/or server.

Role 1 Name


Scenario Step 1 Name

Success Criteria:
Bonus point:


Security and Privacy Considerations

Previous Connectathon Tracks