201805 Versioned API

WIP -- Work in Progress

Track Name

Versioned API

Submitting WG/Project/Implementer Group

FHIR-I + ITS

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.

Justification

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. The server should acknowledge that it has recognized and responded with a specific FHIR version by including a Content-Type header in its response.

Content-Type: application/json+fhir;fhirVersion=3.0

Roles

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

Scenarios

Scenario Step 1 Name

Action:

Precondition:

Success Criteria:

Bonus point:

Previous Connectathon Tracks

201801_Versioned_API