1. WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012

2. Agenda Overview Open Items WADO RESTful API DICOM 2012 Part 18 Supplement XXX Review New Topic: Web Security for REST Questions/Comments

3. Overview David Clunie provided draft copy of DICOM 2012 for future edits Briefed progress to WG-06 Incorporated comments/suggestions from WG-27/WG-06 for further discussion at HIMSS 2012 Started editing DICOM 2012 documents

4. OPEN ITEMS

5. WG-06 Feedback Remove RetrieveInstances in favor of multiple calls to RetrieveInstance. Transfer syntax should be specified in the header or as an explicit RESTful resource, not as a parameter. If the transfer syntax cannot be supported, proper error code should return. The focus of WADO RESTful API should be on transport as opposed to presentation or processing. For example, supporting window regions is the role of a JPIP streamer as opposed to DICOM communication. Provide a separate resource or an application/octet-stream to get direct access to the binary for series and instances.

6. WG-06 Feedback (cont) Look at Appendix Y in Part 4 for a description of the mechanisms for accessing frames. Remove WADO:XPath parameter from metadata resource since it is small enough to send over and let the client parse it. Supplement 157 is rejecting the notion of normalized metadata and instead are refactoring into common chunks that can be returned as a multipart response. Multipart Mime vs MAFF – Prefer Multipart Mime over MAFF since it is an established standard where MAFF is still in review. Need to address web security with REST

7. Transfer Syntax Encoding Transfer Syntax using resources – The return transfer syntax could be specified as an explicit resource for each type of transfer syntax …/instances/{instance uid}/xfersyntaxes/1.2.840.10008.1.2 …/instances/{instance uid}/xfersyntaxes/1.2.840.10008.1.2.1 …/instances/{instance uid}/xfersyntaxes/1.2.840.10008.1.2.2 etc – Since the return transfer syntax could be specified for study, series, instance, and frame level requests, this requires a xfersyntaxes folder on each of those resources. – If no transfer syntax is specified, the default transfer syntax would be Explicit VR, Little Endian

8. Transfer Syntax Encoding Transfer Syntax using Content Negotiation – Accept Use Accept in the header to identify the content types that are acceptable Use Accept-Encoding to identify acceptable encodings Both the Accept and Accept-Encoding can be prioritized lists – Response Server finds the highest priority Accept type that it can support and specifies the mime-type of the content in Content-Type Server finds the highest priority Accept-Encoding type that it can support and specifies the type of encoding in Content-Encoding 406 Response Not Acceptable is returned if server and client cannot agree on a mime type or an encoding

9. Transfer Syntax Encoding Proxy Cache – User requests the same resource, but with a different accept- encoding. – The Vary header lets the caching proxy know which fields it needs to consider for matching in subsequent requests. Vary: Accept, Accept-Encoding Vary: * – Cache proxy will know it needs to consider the Accept and Accept- Encoding header for subsequent calls to the same resource in its decision to return the cached version as valid or go back to the server to request it anew.

10. Bulk data vs pixel data Bulk data – Bulk data is returned for the study, series, and instance resources Pixel data – Pixel data is returned for the frame resources. What is bulk data? – Any binary data within a SOP instance, not just the pixel data. – Metadata would have to provide information for how to parse the bulk data. – Makes WADO RS efficient not only for images but other types of binary data. Possible implementation – Add binaryItemId to XML schema for binary DICOM attributes. – binaryItemId identifies the multipart item of the binary value and its length. – Consider adding a resource to pull a specific binary item (ie. so a user could have direct access to a thumbnail).

11. WADO RESTFUL API

12. WADO RESTful API The DICOM WADO RESTful APl resources. An implementation shall support at least one of these endpoints. The endpoints are: – RetrieveStudy - This resource retrieves the full set of DICOM instances related to the study returned in a multipart mime response – RetrieveSeries - This resource retrieves a series as a set of DICOM objects returned in a multipart mime response – RetrieveInstance - This resource retrieves a SOP Instance as a DICOM object returned in a multipart mime response – RetrieveFrames - This resource retrieves a retrieves a range of frames as a set of DICOM objects returned in a multipart mime response – RetrieveMetadata - This action retrieves the study level metadata

13. WADO RESTful Operations NameOperatorResourceAcceptAccept-Encoding RetrieveStudyGET{s}/studies/{study uid}application/dicom application/wado-rs application/octet-stream 1.2.840.10008.1.2 1.2.840.10008.1.2.1 1.2.840.10008.1.2.2 etc RetrieveSeriesGET{s}/studies/{identifier}/series/{series uid}application/dicom application/wado-rs application/octet-stream 1.2.840.10008.1.2 1.2.840.10008.1.2.1 1.2.840.10008.1.2.2 etc RertrieveInstanceGET{s}/studies/{identifier}/series/{series uid}/instances/{instance uid} application/dicom application/wado-rs application/octet-stream 1.2.840.10008.1.2 1.2.840.10008.1.2.1 1.2.840.10008.1.2.2 etc RetrieveFramesGET{s}/studies/{identifier}/series/{series uid}/instances/{instance uid}/frames/{frame list} application/octet-stream1.2.840.10008.1.2 1.2.840.10008.1.2.1 1.2.840.10008.1.2.2 etc RetrieveFramesGET{s}/studies/{identifier}/series/{series uid}/instances/{instance uid}/frames?calculated={f,u,i}[&calculated={f,u,i}…] application/octet-stream1.2.840.10008.1.2 1.2.840.10008.1.2.1 1.2.840.10008.1.2.2 etc RetrieveFramesGET{s}/studies/{identifier}/series/{series uid}/instances/{instance uid}/frames?time={start, end} application/octet-stream1.2.840.10008.1.2 1.2.840.10008.1.2.1 1.2.840.10008.1.2.2 etc RetrieveMetadataGET{s}/studies/{identifier}/metadatatext/xmlgzip gpb etc

14. WADO RESTful API Assumptions – All XML responses shall be encoded as described in the Native DICOM Model defined in PS3.19. – By default, DICOM objects returned shall be encoded in Explicit VR Little Endian (see 8.2.11 for more information on Transfer Syntax UID).

15. RetrieveStudy Request Resource – {SERVICE}/studies/{StudyInstanceUID} SERVICE is the base url for the WADO URI service. This may be a combination of host, port, and protocol(http or https). {StudyInstanceUID} is the unique study instance UID for a single study. Method – GET Accept – application/dicom Specifies to the URI service the response should be DICOM. – application/wado-rs Specifies to the URI service the response should be WADO XML and binary. – application/octet-stream Specifies to the URI service the response should be binary.

16. RetrieveStudy Response The response format depends on the Accept header specified in the request. The three possible response formats are application/dicom, application/wado-rs, and application/octet-stream. All response formats have a content type of multipart/mixed with a boundary separator of BinaryItemBoundary-7afb50349c2148c3a5d6a324891a481c – Type: application/dicom (Content-Type: multipart/mixed) Each item in the multipart response represents a DICOM SOP instance object. The entire multipart response contains every instance for the study specified. – Type: application/wado-rs (Content-Type: multipart/mixed) The first item in the response is the WADO XML metadata for the study specified. Each following item is the bulk data portion of a SOP instance in the study. – Type: application/octet-stream (Content-Type: multipart/mixed) Each item is the bulk data portion of a SOP instance in the study.

17. RetrieveSeries Request Resource – {SERVICE}/studies/{StudyInstanceUID}/series/{SeriesInstanceUID} SERVICE is the base url for the WADO URI service. This may be a combination of host, port, and protocol(http or https). {StudyInstanceUID} is the unique study instance UID for a single study. {SeriesInstanceUID} is the unique series instance UID for a single series. Method – GET Accept – application/dicom Specifies to the URI service the response should be DICOM. – application/wado-rs Specifies to the URI service the response should be WADO XML and binary. – application/octet-stream Specifies to the URI service the response should be binary.

18. RetrieveSeries Response The response format depends on the Accept header specified in the request. The three possible response formats are application/dicom, application/wado-rs, and application/octet- stream. All response formats have a content type of multipart/mixed with a boundary separation of BinaryItemBoundary-7afb50349c2148c3a5d6a324891a481c – Type: application/dicom (Content-Type: multipart/mixed) Each item in the multipart response represents a DICOM SOP instance object. The entire multipart response contains every instance for the series specified. – Type: application/wado-rs (Content-Type: multipart/mixed) The first item in the response is the WADO XML for the series specified. Each following item is the bulk data portion of a SOP instance in the series. – Type: application/octet-stream (Content-Type: multipart/mixed) Each item is the bulk data portion of a SOP instance in the series.

19. RetrieveInstance Request Resource – {SERVICE}/studies/{StudyInstanceUID}/series/{SeriesInstanceUID}/instances/{S OPInstanceUID} SERVICE is the base url for the WADO URI service. This may be a combination of host, port, and protocol(http or https). {StudyInstanceUID} is the unique study instance UID for a single study. {SeriesInstanceUID} is the unique series instance UID for a single series. {SOPInstanceUID} is the unique SOP instance UID for a single instance. Method – GET Accept – application/dicom Specifies to the URI service the response should be DICOM. – application/wado-rs Specifies to the URI service the response should be WADO XML and binary. – application/octet-stream Specifies to the URI service the response should be binary.

20. RetrieveInstance Response The response format depends on the Accept header specified in the request. The three possible response formats are application/dicom, application/wado-rs, and application/octet-stream. Response format for application/wado-rs has a content type of multipart/mixed with a boundary separation of BinaryItemBoundary- 7afb50349c2148c3a5d6a324891a481c, otherwise the response format is application/octet-stream. – Type: application/dicom (Content-Type: application/octet- stream ) A single item containing the DICOM SOP instance object. – Type: application/wado-rs (Content-Type: multipart/mixed) The first item in the response is the WADO XML metadata for the SOP instance specified. Each following item is the bulk data portion of the SOP instance. – Type: application/octet-stream (Content-Type: multipart/mixed) Each item contains the bulk data portion of the SOP instance.

21. RetrieveFrames Request Simple Frame List Resource – {SERVICE}/studies/{StudyInstanceUID}/series/{SeriesInstanceUID}/instances/{S OPInstanceUID}/frames/{FrameList} SERVICE is the base url for the WADO URI service. This may be a combination of host, port, and protocol(http or https). {StudyInstanceUID} is the unique StudyInstanceUID for a single study. {SeriesInstanceUID} is the unique SeriesInstanceUID for a single series. {SOPInstanceUID} is the unique SOPInstanceUID for a single instance. {FrameList} is a list of one or more monotonically increasing frame numbers (ie. 6,10,18,24). Method – GET Accept – application/octet-stream Specifies to the URI service the response should be binary.

22. RetrieveFrames Request Calculated Frame List Resource – {SERVICE}/studies/{StudyInstanceUID}/series/{SeriesInstanceUID}/instances/{S OPInstanceUID}/frames?calculated={First,Upper,Incr}[&calculated={First,Upper,Incr}…] SERVICE is the base url for the WADO URI service. This may be a combination of host, port, and protocol(http or https). {StudyInstanceUID} is the unique StudyInstanceUID for a single study. {SeriesInstanceUID} is the unique SeriesInstanceUID for a single series. {SOPInstanceUID} is the unique SOPInstanceUID for a single instance. calculated is one or more tuples {First,Upper,Incr} containing the first frame number, the upper limit, and the increment between frames as defined in PS3.4 Annex Y. Method – GET Accept – application/octet-stream Specifies to the URI service the response should be binary.

23. RetrieveFrames Request Time Range Frame List Resource – {SERVICE}/studies/{StudyInstanceUID}/series/{SeriesInstanceUID}/instances/{S OPInstanceUID}/frames?time={Start,End} SERVICE is the base url for the WADO URI service. This may be a combination of host, port, and protocol(http or https). {StudyInstanceUID} is the unique StudyInstanceUID for a single study. {SeriesInstanceUID} is the unique SeriesInstanceUID for a single series. {SOPInstanceUID} is the unique SOPInstanceUID for a single instance. Time is a single pair {Start,End} containing the start and end time in seconds relative to the value of the Content Time (0008,0033) as defined in PS3.4 Annex Y. Method – GET Accept – application/octet-stream Specifies to the URI service the response should be binary.

24. RetrieveFrames Response The response format has a content type of multipart/mixed with a boundary separation of BinaryItemBoundary- 7afb50349c2148c3a5d6a324891a481c – Type: application/octet-stream (Content-Type: multipart/mixed) Each item is the pixel data portion of a frame in the SOP Instance.

25. RetrieveMetadata Request Resource – {SERVICE}/studies/{StudyInstanceUID}/metadata SERVER_ROOT is the base url for the web servers WADO service. This may be a combination of host, port, and protocol(http or https). {StudyInstanceUID} is the unique study instance UID for a single study. Method – GET Accept – text/xml Specifies to the URI service the response should be WADO XML.

26. RetrieveMetadata Response The response format is text/xml with the metadata in WADO XML format for the entire study.

27. SUPPLEMENT XXX REVIEW DICOM 2012 Part 18

28. Supplement XXX Web Access to DICOM Persistent Objects by RESTful Services (WADO-RS) Part 2 - Conformance – A.4.2 - AE Specifications – Annex I - Conformance Statement Sample WADO Service – I.7 - Security Part 17 - Explanatory Information – Annex III - Evolution of WADO to RESTful Services Part 18 - Web Access to DICOM Persistent Objects (WADO) – 5 - Symbols and Abbreviated Terms – 6 - Data Communication Requirements – 6.1 - Interaction – 6.5 - RS Request/Response – 8 - Parameters – Appendix F - Example Requests/Responses

29. WEB SECURITY

30. Security Topics Authentication – Authentication is orthogonal to the WADO RESTful API – WADO RS servers must support HTTP BASIC authorization as a minimum (over SSL) – Strongly recommend that WADO RS servers also support Digest Authorization SSL Client Certificates – WADO RS servers can optionally support Sessions or other authentication mechanisms Local Domain Sessions (Kerberos) Cross Domain Sessions (Shibboleth)

31. Sessions (Local Domain) User requests AS for connection to Service (user name + server name) AS generates random session key KRS, sends credentials and ticket to user Credentials: EKU(user name+KRS) Ticket: EKS(server name+KRS) User gets session key, validates user name, generates authenticator DKU(EKU (user name+KRS)) Authenticator: EKRS(shared secret) User sends authenticator and ticket to Service Service gets session key, validates server name, validates shared secret DKU(EKU (server name+KRS)) DKRS(EKRS(shared secret)) WADO RESTful Server WADO RESTful Server Authentication Service (AS) User KU KS KRS request credentials+ticket authenticator+ticket 1 2 3 4 5 6 KDC

32. Domain 2 Domain 1 Discovery Service Discovery Service WADO RESTful Server WADO RESTful Server Service Provider Service Provider Active Directory LDAP Identity Provider User Identity Provider User App Container Attributes from Claims 1 1 1 1 2 2 4 4 2 2 claims 3 3 3 3 Sessions (Cross Domain)

33. Domain 2 Domain 1 Discovery Service Discovery Service WADO RESTful Server WADO RESTful Server Service Provider Service Provider Active Directory LDAP Identity Provider User Identity Provider User App Container Sessions (Cross Domain) 5 5 5 5

34. Questions/Comments TBD

35. BACKUP