This wiki has undergone a migration to Confluence found Here
<meta name="googlebot" content="noindex">

Difference between revisions of "201801 Versioned API"

From HL7Wiki
Jump to navigation Jump to search
(Created page with "Jan 2018 Proposals __NOTOC__ =Track Name= Versioned API ==Submitting WG/Project/Implementer Group== FHIR-I + ITS ==...")
 
 
(15 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 +
[http://wiki.hl7.org/index.php?title=Category:201801_FHIR_Connectathon_Track_Proposals Return to Jan 2018 Proposals]
 
[[Category:201801_FHIR_Connectathon_Track_Proposals|Jan 2018 Proposals]]
 
[[Category:201801_FHIR_Connectathon_Track_Proposals|Jan 2018 Proposals]]
  
Line 5: Line 6:
  
 
Versioned API
 
Versioned API
 +
 +
=Orientation Materials=
 +
 +
[https://drive.google.com/file/d/1yslaKhlN9AQEC2GkUyAHWayOkJGfxx80/view?usp=sharing Orientation Slides]
 +
 +
[https://youtu.be/iwgkLlF5WV8 Versioned API Orientation with Grahame Grieve]
  
 
==Submitting WG/Project/Implementer Group==
 
==Submitting WG/Project/Implementer Group==
Line 24: Line 31:
  
 
* Grahame Grieve (server + client)
 
* Grahame Grieve (server + client)
* ?
+
* Cerner (server)
  
 
==Roles==
 
==Roles==
Line 48: Line 55:
 
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
 
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
+
   Accept: application/fhir+json;fhir-version=X
  
where X is the formal release (2,3, or 4 for the current build at this time)
+
where X is the formal release (`r2`,`r3`, or `r4` for the current build at this time)
 +
(alternately X could be a semantic version number `1.0`, `1.6` or `3.0`.  The patch level on the version number is probably not necessary)
 +
Note that a list of acceptable versions can be supplied, and the first one matched by the server should be replied with.  The server would specify which on in the `Content-Type` reply header.
  
 
==== Criteria ====
 
==== Criteria ====
Line 66: Line 75:
  
 
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).  
 
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).  
 +
 +
--[[User:Alexander Henket|Alexander Henket]] ([[User talk:Alexander Henket|talk]]) 12:40, 21 February 2018 (EST) Examples?
 +
    {
 +
        "resourceType": "Parameters",
 +
        "parameter": [
 +
            {
 +
                "name": "version",
 +
                "valueString": "r2"
 +
            },
 +
            {
 +
                "name": "version",
 +
                "valueString": "r3"
 +
            }
 +
        ]
 +
    }
 +
 +
    <Parameters xmlns="http://hl7.org/fhir">
 +
        <parameter>
 +
            <name value="version"/>
 +
            <valueString value="r2"/>
 +
        </parameter>
 +
        <parameter>
 +
            <name value="version"/>
 +
            <valueString value="r3"/>
 +
        </parameter>
 +
    </Parameters>
 +
  
 
==== Criteria ====
 
==== Criteria ====
Line 73: Line 109:
 
* Bonus: if the client request is plain json (not FHIR json) then the server returns a simple json containing a versions array
 
* 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"]
+
    "versions": ["r2", "r3"]
}
+
  }
 +
 
 +
--[[User:Alexander Henket|Alexander Henket]] ([[User talk:Alexander Henket|talk]]) 12:16, 21 February 2018 (EST) Q: for Accept XML I'd like to return XML. E.g.
 +
    <versions>
 +
        <version>r2</version>
 +
        <version>r3</version>
 +
    </versions>
 +
 
 +
If we go for semver versions, something like <1.0/> would become awkward and /versions/version is easier to work with than /versions/*/local-name()
  
 
===Scenario #3: Explicit Version Conversion ===
 
===Scenario #3: Explicit Version Conversion ===
Line 90: Line 134:
  
 
Notes:
 
Notes:
* this sc
+
* this scenario is the actual expectation for multi-versioned API: the URL identifies a single resource
This scenario may be used with resources other than patient that
+
* it's up to the server how it performs the conversion in the backgroudn
===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 [[http://docs.smarthealthit.org/authorization/backend-services/]]. For the purpose of this connectathon, servers need only support the scope system/*.read
+
===Scenario #4: Implicit Version Conversion ===
  
 +
====Action====
 +
Client posts/puts Patient resource of one version to the server but claims it is another version. 
  
 
==== Criteria ====
 
==== Criteria ====
  
* Precondition: Application is registered with the server
+
* Success Criteria: Server reads what it can following version compatibility rules, or returns an error if the differences are not consistent with the versioning rules
* Success Criteria: Client can contain an access token that grants them the right to make the calls in step #1 and Step #2
+
 
 +
Notes:
 +
* This stream needs to test more than just Patient - Patient doesn't have enough changes
  
 
==TestScript(s)==
 
==TestScript(s)==
 
+
The supporting TestScripts have been committed to the FHIR documents Github repository at: https://github.com/FHIR/documents/tree/master/connectathons/NewOrleansJan2018/Connectathon17/Versioned-API
This is an API extension, and will require extensions to the test script resource in order to be tested
 
  
 
==Security and Privacy Considerations==
 
==Security and Privacy Considerations==
  
* Obviously, access to APIs like this in production require both authentication and consent
+
n/a
* 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 [[https://chat.fhir.org/#narrow/stream/implementers/subject/Bulk.20Data.20Access]])
 
* 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
 

Latest revision as of 17:40, 21 February 2018

Return to Jan 2018 Proposals


Track Name

Versioned API

Orientation Materials

Orientation Slides

Versioned API Orientation with Grahame Grieve

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)
  • Cerner (server)

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.

  1. Specifying the FHIR version using a content type parameter
  2. Asking the server which versions it supports
  3. Explicit Version conversion
  4. 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

 Accept: application/fhir+json;fhir-version=X

where X is the formal release (`r2`,`r3`, or `r4` for the current build at this time) (alternately X could be a semantic version number `1.0`, `1.6` or `3.0`. The patch level on the version number is probably not necessary) Note that a list of acceptable versions can be supplied, and the first one matched by the server should be replied with. The server would specify which on in the `Content-Type` reply header.

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).

--Alexander Henket (talk) 12:40, 21 February 2018 (EST) Examples?

   {
       "resourceType": "Parameters",
       "parameter": [
           {
               "name": "version",
               "valueString": "r2"
           },
           {
               "name": "version",
               "valueString": "r3"
           }
       ]
   }
   <Parameters xmlns="http://hl7.org/fhir">
       <parameter>
           <name value="version"/>
           <valueString value="r2"/>
       </parameter>
       <parameter>
           <name value="version"/>
           <valueString value="r3"/>
       </parameter>
   </Parameters>


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"]
 }

--Alexander Henket (talk) 12:16, 21 February 2018 (EST) Q: for Accept XML I'd like to return XML. E.g.

   <versions>
       <version>r2</version>
       <version>r3</version>
   </versions>

If we go for semver versions, something like <1.0/> would become awkward and /versions/version is easier to work with than /versions/*/local-name()

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 scenario is the actual expectation for multi-versioned API: the URL identifies a single resource
  • it's up to the server how it performs the conversion in the backgroudn


Scenario #4: Implicit Version Conversion

Action

Client posts/puts Patient resource of one version to the server but claims it is another version.

Criteria

  • Success Criteria: Server reads what it can following version compatibility rules, or returns an error if the differences are not consistent with the versioning rules

Notes:

  • This stream needs to test more than just Patient - Patient doesn't have enough changes

TestScript(s)

The supporting TestScripts have been committed to the FHIR documents Github repository at: https://github.com/FHIR/documents/tree/master/connectathons/NewOrleansJan2018/Connectathon17/Versioned-API

Security and Privacy Considerations

n/a