wado restful api timothy.culp@harris.com dicom wg-27 february 2012
Post on 28-Mar-2015
219 Views
Preview:
TRANSCRIPT
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
top related