WADO RESTful APItimothy.culp@harris.com

DICOM WG-27 February 2012

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

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

OPEN ITEMS

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.

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

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.2etc

– 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

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

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 it’s decision to return the cached version as valid or go back to the server to request it anew.

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 it’s length.– Consider adding a resource to pull a specific binary item (ie. so a user could

have direct access to a thumbnail).

WADO RESTFUL API

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

WADO RESTful OperationsName Operator Resource Accept Accept-EncodingRetrieveStudy GET {s}/studies/{study uid} application/dicom

application/wado-rsapplication/octet-stream

1.2.840.10008.1.21.2.840.10008.1.2.11.2.840.10008.1.2.2etc

RetrieveSeries GET {s}/studies/{identifier}/series/{series uid} application/dicomapplication/wado-rsapplication/octet-stream

1.2.840.10008.1.21.2.840.10008.1.2.11.2.840.10008.1.2.2etc

RertrieveInstance GET {s}/studies/{identifier}/series/{series uid}/instances/{instance uid}

application/dicomapplication/wado-rsapplication/octet-stream

1.2.840.10008.1.21.2.840.10008.1.2.11.2.840.10008.1.2.2etc

RetrieveFrames GET {s}/studies/{identifier}/series/{series uid}/instances/{instance uid}/frames/{frame list}

application/octet-stream 1.2.840.10008.1.21.2.840.10008.1.2.11.2.840.10008.1.2.2etc

RetrieveFrames GET {s}/studies/{identifier}/series/{series uid}/instances/{instance uid}/frames?calculated={f,u,i}[&calculated={f,u,i}…]

application/octet-stream 1.2.840.10008.1.21.2.840.10008.1.2.11.2.840.10008.1.2.2etc

RetrieveFrames GET {s}/studies/{identifier}/series/{series uid}/instances/{instance uid}/frames?time={start, end}

application/octet-stream 1.2.840.10008.1.21.2.840.10008.1.2.11.2.840.10008.1.2.2etc

RetrieveMetadata GET {s}/studies/{identifier}/metadata text/xml gzipgpbetc

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

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.

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.

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.

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.

RetrieveInstance Request• Resource

– {SERVICE}/studies/{StudyInstanceUID}/series/{SeriesInstanceUID}/instances/{SOPInstanceUID}• 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.

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.

RetrieveFrames RequestSimple Frame List

• Resource– {SERVICE}/studies/{StudyInstanceUID}/series/{SeriesInstanceUID}/instances/

{SOPInstanceUID}/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.

RetrieveFrames RequestCalculated Frame List

• Resource– {SERVICE}/studies/{StudyInstanceUID}/series/{SeriesInstanceUID}/instances/

{SOPInstanceUID}/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.

RetrieveFrames RequestTime Range Frame List

• Resource– {SERVICE}/studies/{StudyInstanceUID}/series/{SeriesInstanceUID}/instances/

{SOPInstanceUID}/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.

Consider making this an “Open Item”

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.

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.

RetrieveMetadata Response• The response format is text/xml with the metadata in WADO

XML format for the entire study.

SUPPLEMENT XXX REVIEWDICOM 2012 Part 18

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

WEB SECURITY

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)

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 RESTfulServer

Authentication Service (AS)

User

• KU

• KU

• KS

• KS• KRS

• request• credentials+ticket

• authenticator+ticket

• 1 • 2

• 3 • 4 • 5

• 6

• KDC

Domain 2

Domain 1

Discovery Service

WADORESTfulServer

ServiceProvider

ActiveDirectory

LDAP

IdentityProvider

User

IdentityProvider

User

App Container

Attributes from Claims

1

1

2

4

2

claims 3

claims3

Sessions (Cross Domain)

Domain 2

Domain 1

Discovery Service

WADORESTfulServer

ServiceProvider

ActiveDirectory

LDAP

IdentityProvider

User

IdentityProvider

User

App Container

Sessions (Cross Domain)

5

5

Questions/Comments• TBD

BACKUP