Imaging Data

Imaging Data

The API calls below show how to use S4S for sharing Imaging Data. The Imaging Data Use Case is aligned with FHIR STU3.

The examples below refer to the following variables:

We’ll also refer to two “request times”:

(Note: a production-quality app might repeat the “broad” queries on an occasional basis — e.g. yearly — as a sanity check, and to discovery any data that may have fallen out of the record.)

Want to propose a change? edit this page!

Authorization expectations: SMART on FHIR OAuth2

Sync for ScienceTM (like Argonaut) uses the OAuth2-based SMART on FHIR authorization specification. But we don’t need all the moving parts. In particular, in Sync for Science we can get away with a minimum of:

  1. “confidential clients”, meaning that apps get assigned a client_id and client_secret to authenticate to EHRs.The general SMART and Argonaut specs also require support for “public clients”, but it’s not strictly a requirement in S4S.

  2. “standalone launch” flow, meaning that the patient (research participant) can begin by interacting with the PMI app, and from there, can launch into an “connect to my EHR” workflow. The general SMART and Argonaut specs also require support for the “EHR launch flow” (where apps launch from an EHR or portal), but it’s not strictly a requirement in S4S.

  3. patient/*.read launch/patient offline_access scopes, meaning that when the app launches, it will ask the EHR for permission to read all data available to the patient, and it will ask to learn the FHIR id of the patient whose records are shared.

We also do not require support for Single Sign-on via OpenID Connect in S4S (though again, it’s part of SMART and Argonaut, and we encourage implementers to support it).

Note on 503 response status and Retry-After hints

The Imaging Data use case is designed to be compatible with existing DICOM-based infrastructure, so that support can readily be built as a layer on top of widely supported PACS operatiosn like DICOM’s C-MOVE and C-FIND. Since these DICOM operations can take several minutes to complete, the S4S client should be prepared to receive a 503 HTTP response code with a Retry-After header indicating how many seconds to wait before re-trying a request. For example, the following response means “try agian after 5 minutes (300 seconds)”:

HTTP/1.1 503 Service Unavailable
Retry-AFter: 300

Server metadata

Return a FHIR capability statement with SMART extensions for OAuth

GET /metadata

ImagingStudy

Includes: a list of imaging studies available for a patient. (TODO: include details from RSNA FHIR Broker.)

On first-connection
GET /ImagingStudy?patient={{patientId}}
Request
GET /api/open-fhir/ImagingStudy?patient=smart-1288992 HTTP/1.1
Host: portal.demo.syncfor.science
Accept: application/json+fhir
Response
On periodic-update
GET /ImagingStudy?patient={{patientId}}&_lastUpdated=gt{{lastCheck}}
Request
GET /api/open-fhir/ImagingStudy?patient=smart-1288992&_lastUpdated=gt2016-04-16 HTTP/1.1
Host: portal.demo.syncfor.science
Accept: application/json+fhir
Response

Each ImagingStudy in the response bundle will include an ImagingStudy.uid value and an ImagingStudy.endpoint reference. These values can be used to retrieve full DICOM data for the study as follows:

  1. The endpoint reference resolves to an Endpoint resource whose Endpoint.url represents a DICOM WADO service. For the example below, assume this URL was https://imaging-server/Patient/smart-1288992/$wado-rs.

  2. The uid value provides a DICOM study unique id. For the example below, assume this uid was urn:oid:2.16.124.113543.6003.1154777499.30246.19789.3503430045.

  3. These vales can be used to formulate a request for DICOM data as follows:

GET https://imaging-server/Patient/smart-1288992/$wado-rs/studies/2.16.124.113543.6003.1154777499.30246.19789.3503430045
Accept: multipart/related; type=application/dicom