![Page 2: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/2.jpg)
Agenda• Overview• Open Items• WADO RESTful API• DICOM 2012 Part 18 Supplement XXX Review• New Topic: Web Security for REST• Questions/Comments
![Page 3: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/3.jpg)
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
![Page 4: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/4.jpg)
OPEN ITEMS
![Page 5: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/5.jpg)
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.
![Page 6: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/6.jpg)
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
![Page 7: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/7.jpg)
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
![Page 8: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/8.jpg)
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
![Page 9: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/9.jpg)
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.
![Page 10: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/10.jpg)
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).
![Page 11: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/11.jpg)
WADO RESTFUL API
![Page 12: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/12.jpg)
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
![Page 13: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/13.jpg)
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
![Page 14: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/14.jpg)
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).
![Page 15: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/15.jpg)
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.
![Page 16: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/16.jpg)
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.
![Page 17: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/17.jpg)
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.
![Page 18: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/18.jpg)
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.
![Page 19: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/19.jpg)
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.
![Page 20: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/20.jpg)
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.
![Page 21: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/21.jpg)
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.
![Page 22: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/22.jpg)
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.
![Page 23: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/23.jpg)
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”
![Page 24: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/24.jpg)
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.
![Page 25: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/25.jpg)
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.
![Page 26: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/26.jpg)
RetrieveMetadata Response• The response format is text/xml with the metadata in WADO
XML format for the entire study.
![Page 27: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/27.jpg)
SUPPLEMENT XXX REVIEWDICOM 2012 Part 18
![Page 28: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/28.jpg)
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
![Page 29: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/29.jpg)
WEB SECURITY
![Page 30: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/30.jpg)
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)
![Page 31: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/31.jpg)
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
![Page 32: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/32.jpg)
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)
![Page 33: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/33.jpg)
Domain 2
Domain 1
Discovery Service
WADORESTfulServer
ServiceProvider
ActiveDirectory
LDAP
IdentityProvider
User
IdentityProvider
User
App Container
Sessions (Cross Domain)
5
5
![Page 34: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/34.jpg)
Questions/Comments• TBD
![Page 35: WADO RESTful API timothy.culp@harris.com DICOM WG-27 February 2012](https://reader036.vdocuments.mx/reader036/viewer/2022081514/5516c2d4550346a25b8b615c/html5/thumbnails/35.jpg)
BACKUP