201801 Versioned API
Track Name
Versioned API
Submitting WG/Project/Implementer Group
FHIR-I + ITS
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)
Proposed Track Lead
Grahame Grieve (Connectathon_Track_Lead_Responsibilities)
Expected participants
- Grahame Grieve (server + client)
- ?
Roles
Server: provides the FHIR API Client: use the FHIR API
Scenarios
The versioning track is divided into 4 scenarios. Scenarios 1 and 2 deal with API differences, and scenarios 3 and 4 deal with managing content differences between FHIR versions.
- Specifying the FHIR version using a content type parameter
- Asking the server which versions it supports
- Explicit Version conversion
- Implicit Version conversion
In theory, the techniques for this stream apply to all resources. However, for simplicity, the stream will focus on searching, reading and writing Patient resources. Servers that do not support read/write on patient resources may still participate.
Scenario #1: Specifying Server Version
Action
Client makes a request of the server for e.g. GET [base]/Patient/example, with the Accept: header containing a standard FHIR content type as negotiated with the server, but also containing the content type parameter
fhir-version: rX
where X is the formal release (2,3, or 4 for the current build at this time)
Criteria
Success Criteria: The server returns a patient resource for the nominated version of FHIR, or an error if it is not supported.
Notes:
- search is required to work correctly for the nominated version of FHIR, and that the careProvider search parameter was renamed. Note also the content of the Patient.contact.relationship code set changed
- for this scenario the server is not required to ensure that the R2/R3/R4 versions of the resource are synchronised (see scenario #3 below)
Scenario #2: Server Version discovery
Action
Client makes the request GET [base]/$versions
Server returns a parameters resource containing one or more version parameters, one for each version supported. The possible versions are (at this time: r2, r3, r4).
Criteria
- Success Criteria: server returns correct list
- Bonus: if the client request is plain json (not FHIR json) then the server returns a simple json containing a versions array
{
"versions": ["r2, r3"]
}
Scenario #3: Explicit Version Conversion
Action
Client posts/puts Patient resource to the server using one version, and [it or another client] reads it as another version. The semantics of the resource must be updated properly
This uses the server to do version conversion of a resource. Note that (for now?) this is 2 calls; we are not testing an inline version conversion operation
Criteria
- Precondition: server claims to support both versions
- Success Criteria: server can convert
Notes:
- this sc
This scenario may be used with resources other than patient that
Scenario Step 3: Smart Backend Services Support
Action
Data Consumer uses the Smart backend services spec to create a session prior to the calls in steps #1/#2
See [[1]]. For the purpose of this connectathon, servers need only support the scope system/*.read
Criteria
- Precondition: Application is registered with the server
- Success Criteria: Client can contain an access token that grants them the right to make the calls in step #1 and Step #2
TestScript(s)
This is an API extension, and will require extensions to the test script resource in order to be tested
Security and Privacy Considerations
- Obviously, access to APIs like this in production require both authentication and consent
- Step 3 tests out application authentication
- for now, it is assumed that consent is managed elsewhere, though extensions may be added to the stream for this (see [[2]])
- Audit: for now, it is assumed that applications will audit the initial FHIR retrieval, and a smart on fhir login, but there are no rules about that
