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:
patientIdindicates the FHIR
Patientin context. For example,
lastCheckindiclates a FHIR
instant, with millisecond-level precision including a timezone. For example,
We’ll also refer to two “request times”:
- first-connection for broad queries that the app will make once, after first approval, to back-fill historical data
- periodic-update for narrow queries the app will make frequently (e.g. weekly)
(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:
“confidential clients”, meaning that apps get assigned a
client_secretto authenticate to EHRs.The general SMART and Argonaut specs also require support for “public clients”, but it’s not strictly a requirement in S4S.
“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.
patient/*.read launch/patient offline_accessscopes, 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).
503 response status and
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
Return a FHIR capability statement with SMART extensions for OAuth
Includes: a list of imaging studies available for a patient. (TODO: include details from RSNA FHIR Broker.)
GET /api/open-fhir/ImagingStudy?patient=smart-1288992 HTTP/1.1 Host: portal.demo.syncfor.science Accept: application/json+fhir
GET /api/open-fhir/ImagingStudy?patient=smart-1288992&_lastUpdated=gt2016-04-16 HTTP/1.1 Host: portal.demo.syncfor.science Accept: application/json+fhir
Explanation Of Benefit
Includes: details about benefits that a patient has received through their insurance coverage (TODO: include details from BB on FHIR profiles).
GET /api/open-fhir/ExplanationOfBenefit?patient=smart-1288992 HTTP/1.1 Host: portal.demo.syncfor.science Accept: application/json+fhir
GET /api/open-fhir/ExplanationOfBenefit?patient=smart-1288992&_lastUpdated=gt2016-04-16 HTTP/1.1 Host: portal.demo.syncfor.science Accept: application/json+fhir
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:
The endpoint reference resolves to an Endpoint resource whose Endpoint.url represents a DICOM WADO service. For the example below, assume this URL was
The uid value provides a DICOM study unique id. For the example below, assume this uid was
These vales can be used to formulate a request for DICOM data as follows:
GET https://imaging-server/Patient/smart-1288992/$wado-rs/studies/220.127.116.11543.6003.1154777499.30246.19789.3503430045 Accept: multipart/related; type=application/dicom