RESTful Web Services

It consists of four sets:

• Studies Web Service - Study, series, instances, frames, metadata, bulkdata (Currently supported).
• Worklist Web Service - Unified Procedure Steps (UPS-RS) worklist.
• Non-Patient Instance Service – Color palettes, hanging protocol, procedure code, implant templates.
• Storage Commitment Service - Enables a user agent to request the safekeeping of instances on an origin server.

In addition, there is a special transaction defined for user agent to retrieve a machine-readable description of the service(s) implemented by an origin server called Retrieve Capabilities transaction (HTTP OPTION call on a resource).

Studies Web Service

The Studies resource enables a user agent to store, retrieve, update, and search an origin server for DICOM Studies, Series, and Instances, along with their /metadata, /rendered, and /thumbnail variants; as well as frames, bulk data and pixel data.

The Retrieve transaction of this service is also known as WADO-RS. The Store transaction of this service is also known as STOW-RS. The Search transaction of this service is also known as QIDO-RS. All Studies services require support for Retrieve Capabilities Transaction.

Resource Level Services and Transaction

• Resources (Study, Series, Instances, Frames, Metadata, Bulkdata, PixelData, Thumbnail, Rendered) and transactions (store, retrieve, search, etc.). For a full list of resources, refer to 10.1.1 Resource Descriptions.

• Studies Web Service transaction

  • Query is perform using HTTP GET method (aka QIDO-RS).

  • Retrieve DICOM instance (DICOM part 10 file or Rendered representation) - HTTP Method GET. (aka WADO-RS).

  • Store-HTTP Method POST (STOW-RS) – This is only support DICOM resources as a single instance, or as separate Metadata and Bulkdata. Target resource are "/studies" or "/studies/{study instance UID}".

  • Discover services – Retrieve Capabilities transaction at each resource level (HTTP method is OPTIONS).

Retrieve Capabilities Transaction

A machine-readable Capabilities Description of the service(s) implemented by an origin server. All RESTful services are required to implement this transaction. Capabilities Description describes the transactions, resources, representations, etc. that are supported by the service(s). Making the HTTP OPTIONS query against an end-point, and a WADL response will be returned explaining the various options and that are supported.

This allows for client application (user agent) to programmatically interrogate the capabilities of origin server for a specific resource level or resource instance level. For example, if the user want to check if a server supports retrieval of DICOM instance metadata as DICOM XML (without the bulk data) for a specific SOP instance, the following must be sent:

OPTIONS http://www.hospital-stmarco/radiology/studies/1.2.250.1.59.40211.12345678.678910 /series/1.2.250.1.59.40211.789001276.14556172.67789 /instances/1.2.250.1.59.40211.2678810.87991027.899772.2/metadata HTTP/1.1 
Host: www.hospital-stmarco 
Accept: multipart/related; type="application/dicom+xml" 
Origin: http://localhost:65232 

Request

The request shall have the following syntax:

OPTIONS SP / SP version CRLF 
Accept: 1#media-type CRLF 
*(header-field CRLF) 
CRLF 

Target Resource

The Target Resource for this transaction is an origin server (e.g. Base URI ("/") for the service). If the capabilities transaction is requested for target resource baseURL/Studies, the origin server should responds with all the capabilities it supports at that resources level and lower level resources, such as series, series/metadata, Instance, instance/metadata, or frame level. For the full list of target resources, refer to 10.1.1 Resource Descriptions.

Query Parameters

No Query Parameters.

Header Fields

Payload

No payload.

Behavior

Origin server shall return a Capabilities Description, as defined in Annex H, in an Acceptable Media Type. The WADL document shall contain one top-level "application" element and it should contain one "resources" element whose "base" attribute value is the base URL for the service. Additionally, the WADL content shall include a "resource" element for the Target Resource specified in the request describing all methods and child resources for the specified resource and each of its children.

Origin server support of Retrieve Capabilities transaction should support the following use cases for a client application:

• PACS Admin needs to configure a DICOMweb client (a viewer) based on capabilities supported by the origin server. This will be using Studies resource as target.
• A DICOMweb Viewer, have logic to identify what capabilities DICOMweb server supports at different resource or resource instance level. This will require each target resource to support capabilities transaction. For example, do the server support rendering Structured Report (SR) in HTML or PDF format? if not, it will get the DICOM JSON.

Response

The response shall have the following syntax:

version SP status-code SP reason-phrase CRLF 
[Content-Type: media-type CRLF] 
[(Content-Length: uint) / (Transfer-Encoding: encoding) CRLF] 
*(header-field CRLF) 
CRLF 
[payload / status-report] 

Header Fields

Payload

• A success response shall have a payload containing a Capabilities Description in the Selected Media Type.
• The Capabilities Description shall conform to the requirements and structure defined in PS3.18 Annex H.
• A failure response payload may contain a Status Report describing any failures, warnings, or other useful information.

Media Types

Media types supported by the Retrieve Capabilities service are application/vnd.sun.wadl+xml (Web Application Description Language) or application/json.

Status Codes

• Success - 200 (OK)
• Failure - 400 (Bad Request)

Example

Check for Capability of Retrieving Metadata as XML:

OPTIONS http://www.hospital-stmarco/radiology/studies/1.2.250.1.59.40211.12345678.678910 /series/1.2.250.1.59.40211.789001276.14556172.67789 /instances/1.2.250.1.59.40211.2678810.87991027.899772.2/metadata HTTP/1.1 
Host: www.hospital-stmarco 
Accept: multipart/related; type="application/dicom+xml" 
Origin: http://localhost:65232 

Retrieve Transaction (WADO-RS)

This Transaction uses the GET method. The media type in the response payload will depend on the Target URI and the Query Parameters. For example, Instances as application/dicom, Metadata as application/dicom+json or application/dicom+xml and rendered Instances as application/jpeg images.

Request

The request shall have the following syntax:

GET SP "/" {/resource} {?parameter*} SP version CRLF 
Accept: 1#media-type CRLF 
*(header-field CRLF) 
CRLF 

Where parameter is one of the Query Parameters defined for the Target Resource below:

Target Resources

Instance Resources

The following Instance Resources are used to retrieve instances.

Metadata Resources

Used to retrieve the metadata of instances without retrieving bulk data. Retrieving a Series Metadata resource retrieves all the metadata for all individual instances contained in the Series. Retrieving a Study Metadata resource retrieves all the metadata for all individual instances contained in all the Series.

• An implementation interested in just study level or series level metadata, should use Search Transaction on the All Studies or Study's Series resources, matching against the Study Instance UID and using &includefield to specify the metadata of interest (e.g., tags to include).

• Retrieve Transaction Metadata Resources

  Resources	URI Template
  Study Metadata	/studies/{study}/metadata
  Series Metadata	/studies/{study}/series/{series}/metadata
  Instance Metadata	/studies/{study}/series/{series}/instances/{instance}/metadata

• Don't include Group 0002 File Meta Information Data Elements.

• Photometric Interpretation (0028,0004) may differ depending on the Transfer Syntax.
• If Transfer Syntax UID (0002,0010) is needed for Media Type to retrieve the image data (bulk data), one can use Search Transaction's Available Transfer Syntax UID (0008,3002).

Rendered Resources

Used to retrieve representations of a DICOM Resource rendered as appropriate images, videos, text documents, or other representations. Its primary use case is to provide user agents with a simple means to display medical images and related documents, without requiring deep knowledge of DICOM data structures and encodings.

• Rendered Study URI: /studies/{study}/rendered
• Rendered Series URI: /studies/{study}/series/{series}/rendered
• Rendered Instance URI: /studies/{study}/series/{series}/instances/{instance}/rendered
• Rendered Frames URI: /studies/{study}/series/{series}/instances/{instance}/frames/{frames}/rendered

Thumbnail Resources

Used to retrieve a rendered representation appropriate to stand for its parent DICOM resource.

• Study Thumbnail URI: /studies/{study}/thumbnail
• Series Thumbnail URI: /studies/{study}/series/{series}/thumbnail
• Instance Thumbnail URI: /studies/{study}/series/{series}/instances/{instance}/thumbnail
• Frame Thumbnail URI: /studies/{study}/series/{series}/instances/{instance}/frames/{frames}/thumbnail

Bulkdata Resources

Used to retrieve data elements (typically containing large data, such as pixel data) extracted from DICOM instances.

• Study Bulkdata URI: /studies/{study}/bulkdata
• Series Bulkdata URI: /studies/{study}/series/{series}/bulkdata
• Instance Bulkdata URIL: /studies/{study}/series/{series}/instances/{instance}/bulkdata
• Bulkdata URI: {bulkdataURI}

Note: Bulkdata resources that contain pixel data can be retrieved equivalently using Pixel Data Resource.

Pixel Data Resources

Used to retrieve data elements containing top-level pixel data from DICOM instances.

• Study Pixel Data URI: /studies/{study}/pixeldata
• Series Pixel Data UIR: /studies/{study}/series/{series}/pixeldata
• Instance Pixel Data URI: /studies/{study}/series/{series}/instances/{instance}/pixeldata
• Frame Pixel Data URI: /studies/{study}/series/{series}/instances/{instance}/frames/{frames}

Note: Frame Pixel Data is inherently pixel data so a /pixeldata sub resource is not needed in the URI Template.

Query Parameters

Header Fields

Payload

No payload.

Behavior

Origin server shall prepare representation(s) of the Target Resource in the Selected Media Type.

Response

The response shall have the following syntax:

version SP status-code SP reason-phrase CRLF 
[Content-Type: media-type CRLF] 
[(Content-Length: uint / Transfer-Encoding: encoding) CRLF] 
[Content-Location: url CRLF] 
*(header-field CRLF) 
CRLF 
payload / status-report 

Header Fields

The media type of the payload is required if response has a payload.

• Name: Content-Type
• Value: media-type

Payload

• All success response shall have a payload containing one or more representations of the Target Resource in the Selected Media Type and payload conform to PS 3.18 section 8.6.
• A failure response payload should contain a Status Report describing any failures, warnings, or other useful information.
• Instance Resource Payload
• Metadata Resource Payload
• Rendered Resource Payload
• Thumbnail Resource Payload
• Bulkdata Resource Payload
• Pixel Data Resource Payload

Media Types

The origin server shall support the media types specified as default or required in PS3.18 Table 10.4.4-1.

Status Code

Refer to 10.4.3.1 Status Codes.

Store Transaction (STOW-RS)

This transaction uses the POST method to Store representations of Studies, Series, and Instances contained in the request payload.

• The resource (DICOM Resource) can be PS3.10 representation of DICOM instance (full DICOM file with part 10 header elements).
• Metadata (JSON or XML) and Bulkdata representations of SOP Instances.
• Bulkdata can be compressed or uncompressed (mp4, image, JPEG, PNG, GIF, etc.).

Note: Implementation should add hooks for reconciliation (Patient Name, Patient ID, and Accession Number) as uploaded studies could be originated in another organization will have different PID.

Request

The request shall have the following syntax:

POST SP "/" {/resource} SP version CRLF 
Accept: 1#media-type CRLF 
Content-Type: dicom-media-type CRLF 
(Content-Length: uint / Transfer-Encoding: encoding) CRLF 
*(header-field CRLF) 
CRLF 
payload 

Target Resource

• Studies: /studies - set of representations that may have different Study Instance UIDs.
• Study: /studies/{study} - set of representations that belong to the same Study (all payloads have the same Study Instance UID).

Query Parameters

No Query Parameters.

Header Fields

Payload

The payload shall consist of either:

• PS3.10 representation of DICOM instance (DICOM file with meta header group 2 elements).
• Metadata and Bulkdata representations of SOP Instances.
• XML representations of Metadata shall be encoded as described in the Native DICOM Model with one representation per XML object.
• JSON representations of Metadata shall be encoded as an array of DICOM JSON Model Objects in a single representation.
• Representations of Metadata may omit Attributes of the Image Pixel Description Macro for referenced pixel data whose representation is encoded in one of the media types.
• The Metadata shall include only the DICOM Dataset (without Bulkdata), and in particular shall not include any Group 0002 File Meta Information Data Elements.
• Uncompressed Bulkdata (including pixel data but with the exception of the Encapsulated Document (0042,0011) element) shall be encoded as application/octet-stream with one representation per Bulkdata item.
• Compressed pixel data for a Single Frame Image shall be encoded as one compressed Bulkdata representation.
• Compressed pixel data for a Multi-Frame Image shall be encoded as multiple Single Frame Image compressed Bulkdata representations.
• Compressed pixel data for a Video shall be encoded as one compressed Bulkdata representation.
• The Encapsulated Document (0042,0011) Bulkdata element shall be encoded using the media-type from the MIME Type of the Encapsulated Document (0042,0012) Attribute with one representation per document.

Behavior

• This transaction stores one or more new instances, and adds them to new or existing Series and Studies.
• While creating resources from the representations, the origin server may coerce or replace the values of data elements, such as Patient Name, Patient ID, and Accession Number.
  • If any Attribute is coerced or corrected, the Original Attribute Sequence (0400,0561) shall be included in the stored DICOM Object.
  • Origin Server may include Original Attribute Sequence (0400,0561) in the Store Instances Response Module (see Annex I) in the response.
• The origin server shall encapsulate or convert any compressed pixel data received as Bulkdata into an appropriate DICOM Transfer Syntax as defined in Table 10.5.2-1.
• In the case of pixel data supplied as image/gif or image/png, the origin server may transform the color representation from indexed color to true color (RGB) as necessary to conform to any Photometric Interpretation constraints specified by the IOD.
• An animated image/gif will be converted into a multi-frame image by transforming the frame deltas into fully decoded frames. Note: Multiple-image Network Graphics (MNG) is not supported.
• Any transparency information present in an image/gif or image/png file will be discarded, since DICOM does not support the concept of transparency.
• If an alpha channel is supplied in an image/png file, the alpha channel will be discarded.

Response

The response shall have the following syntax:

version SP status-code SP reason-phrase CRLF 
[Content-Type: media-type CRLF] 
[(Content-Length: uint CRLF / Transfer-Encoding: encoding CRLF)] 
*(header-field CRLF) 
CRLF 
store-instances-response-module 

• The response shall contain an appropriate status code.
• If any element is coerced or corrected, the Original Attribute Sequence (0400,0561) shall be included in the DICOM Object that is stored and may be included in the Store Instances Response Module (see PS3.18 Annex I) in the response.

Header Fields

The origin server shall support header fields as required in Table 10.5.3-2.

• All success responses shall also contain the Content Representation and Payload header fields with appropriate values.
• It is recommended that the text returned in the Warning header field (see RFC7234 Section 5.5) contain a DICOM Status Code (see PS3.4 and Annex C "Status Type Encoding (Normative)" in PS3.7) and descriptive reason.
  Example: Warning: A700 : Out of memory

Payload

• A success response payload shall contain a Store Instances Response Module.
• A failure response payload may contain a Status Report describing any failures, warnings, or other useful information.

Media Types

The origin server shall support the default and required media types as specified in Table 10.5.4-1.

Status Code

• Success

  • 200 (OK).
  • 202 (Accepted) - The origin server stored some of the instances but warnings or failures exist for others. Additional information regarding the errors may be found in the response message body.

• Failure

  • 400 (Bad Request) - Unable to store instances due to bad syntax.
  • 409 (Conflict) - Origin server was unable to store instances due to a conflict in the request (e.g., unsupported SOP Class or Study Instance UID mismatch).
  • 415 (Unsupported Media Type) - Does not support the media type specified in the Content-Type header field of the request.

Search Transaction (QIDO-RS)

This transaction uses the GET method to search for Studies, Series, and Instances managed by the origin server.

Request

The request shall have the following syntax:

GET SP "/" {/resource} {?search*} SP version CRLF 
Accept: 1#search-media-type CRLF 
*(header-field CRLF) 
CRLF 
Where search-media-type =multipart/related; type="application/dicom+xml"/ dicom-json 

Target Resources

The Target Resource Path component of the Target URI specifies the collection of resources that is the target of the search.

• An origin server that is a native implementation shall support all Mandatory (M) resources specified in the Native column in Table 10.6.1-1.
• An origin server that is a DIMSE Proxy implementation shall support all Mandatory (M) resources specified in the Proxy column in Table 10.6.1-1.
• Table 10.6.1-2 shows the resources supported by the search transaction along with a description of the search performed and the results returned.

Query Parameters

• The origin server shall support Query Parameters as required in Table 8.3.4-1.

• The user agent shall supply Query Parameters as required in Table 8.3.4-1.

  Term	Value	User Agent	Origin Server	Description
  search	= match / fuzzymatching / includefield / limit / offset	O	M
  match	; See attribute matching rules below	O	M	Section 8.3.4.1
  fuzzymatching	= "fuzzymatching" "=" true / false	O	M	Section 8.3.4.2
  includefield	= "includefield" "=" 1#attribute / "all"	O	M	Section 8.3.4.3
  limit	= "limit" "=" uint ; Maximum number of results	O	M	Section 8.3.4.4
  offset	= "offset" "=" uint ; Number of skipped results	O	M	Section 8.3.4.4

• Attribute/Value Pair Requirements - The user agent may include the following Attributes in the request:

  • Patient IE Attributes (see Section 10.6.1.2.3).
  • Study IE Attributes (only allowed if the resource is All Studies, All Series, or All Instances).
  • Series IE Attributes (only allowed if the resource is Study's Series, All Series, Study's Instances, or All Instances).
  • Composite Instance IE Attributes (only allowed if the resource is Study's Instances, Study Series' Instances, or All Instances).
  • Additional Query/Retrieve Attributes (see Section C.3.4 in PS3.4).
  • Private Data Element Tags and their corresponding Private Creator Element Tags.
  • Timezone Offset From UTC (0008,0201).

• Attribute Matching – The syntax of the match Query Parameter:

  match = normal-match / uid-list-matchnormal-match = 1*("&" attribute "=" value)uid-list-match = 1*("&" attribute "=" 1#value)attribute = (attribute-id) *("." attribute-id)attribute-id = tag *("." tag) / keyword *("." keyword)tag = 8HEXDIG

keyword= ; A keyword from Table 6-1 "Registry of DICOM Data Elements" in PS3.6.

• One or more DICOM Attribute/Values pairs specify the matching criteria for the search.
• Each search transaction defines which Attributes are required or permitted.

• DICOM Attribute/Values pairs satisfy the following requirements:

  • Each attribute-id shall be a Data Element Tag or Keyword and not repeated.
  • Each attribute in the Query Parameter shall have a single value, unless the associated DICOM Attribute allows UID List matching, in which case the value is a comma-separated list of UIDs.
  • If a tag represents a Private Data Element the query shall also include a corresponding Private Creator Element.
  • The acceptable values are determined by the types of matching allowed by C-FIND for its associated attribute (Follow PS3.4 rules) and the match Query Parameter corresponds to DIMSE Matching Keys.
  • All characters in values that are not qp-chars shall be percent-encoded and all non-ASCII characters shall be percent encoded.
  • The following US-ASCII characters "#", "[", "]", "&", "=", and "," shall be percent encoded in any Query Parameter.
  • Required Matching Attributes. See Table 10.6.1-4. Required IE Levels by Resource. The origin server shall support the matching Attributes specified in Table 10.6.1-5 for each supported IE Level.

• Matching Rules:

  • Types of matching allowed by C-FIND and matching results generated according to the Hierarchical Search Method described in PS3.4.
  • Combined date-time matching shall be performed as specified in Section C.2.2.2.5 "Range Matching" in PS3.4.
  • If an origin server is acting as a proxy for a C-FIND SCP that does not support combined date-time matching, it shall perform a C-FIND request using only the date and filter any results that are outside the time range before returning a response.
  • If the Timezone Offset From UTC (0008,0201) Attribute is specified in the request, dates and times in the request are to be interpreted in the specified time zone.
• Fuzzy Matching of Person Names - A single parameter specifies whether Fuzzy Matching of Person Names is to be performed.
  • Fuzzy Matching is optional for the user agent and the origin server.
  • When this parameter is not present its value is "false". fuzzymatching = "fuzzymatching" "=" ("true" / "false").
  • If the origin server supports Fuzzy Matching, this should be documented in the Conformance Statement and the Retrieve Capabilities response.
  • If the value is "true" and the origin server does not support Fuzzy Matching, then search shall be performed without Fuzzy Matching and response shall include the following HTTP Warning header:
  • Warning: 299 : The fuzzymatching parameter is not supported. Only literal matching has been performed.
  • where is the base URI for the origin server. This may be a combination of scheme, authority, and path.
  • The response includes a payload containing an appropriate Status Report.

• Attributes to include in the Response.

  • A parameter specifies the Attributes that should be included in the response. The value is either a comma-separated list of attributes, or the single keyword "all", which means that all available attributes of the object should be included in the response.
    includefield = *("includefield" "=" (1#attribute / "all") )

• Examples of Search URIs with valid Attribute/value pairs:

  /studies?PatientID=11235813 
  /studies?PatientID=11235813&StudyDate=20130509 
  /studies?00100010=SMITH*&00101002.00100020=11235813&limit=25 
  /studies?00100010=SMITH*&OtherPatientIDsSequence.00100020=11235813 
  /studies?PatientID=11235813&includefield=00081048,00081049,00081060 
  /studies?PatientID=11235813&includefield=00081048&includefield=00081049&includefield=00081060 
  /studies?PatientID=11235813&StudyDate=20130509-20130510 
  /studies?StudyInstanceUID=1.2.392.200036.9116.2.2.2.2162893313.1029997326.94587,1.2.392.200036.9116.2.2.2.2162893313.1029997326.94583 
  /studies?00230010=AcmeCompany&includefield=00231002&includefield=00231003 
  /studies?00230010=AcmeCompany&00231001=001239&includefield=00231002&includefield=00231003 

Header Fields

• Origin server shall support header fields as required in Table 10.6.1-6.
• User agent shall supply in the request header fields as required in Table 10.6.1-6.

Payload

No payload.

Response

The response shall have the following syntax:

version SP status-code SP reason-phrase CRLF 
[Content-Type: media-type CRLF] 
[Content-Location: url CRLF] 
[(Content-Length: uint / Transfer-Encoding: encoding) CRLF] 
*(header-field CRLF) 
CRLF 
[payload / status-report] 

Status Codes

• Success
  • 200 - (OK)
  • 204 (No Content) - Success no match.
• Failure
  • 400 (Bad Request)
  • 413 (Payload Too Large - The search was too broad, and the body of the response should contain a Status Report with additional information about the failure).

Header Fields

Refer to Table 10.6.3-2. Response Header Fields.

Payload

• A success response shall contain a list of matching results in an Acceptable Media Type.

• A failure response payload may contain a Status Report describing any failures, warnings, or other useful information.

• Response Payload at target resource level

  • Study Resource Search Response Payload
  • For each matching Study, the origin server response shall contain Attributes in accordance with Table 10.6.3-3.
  • In addition, the response shall contain:
    • All other Study level Attributes passed as match or includefield parameters in the request that are supported by the origin server.
    • If a Private Data Element has been specified as an include parameter and it is supported by the origin server, the Private Data Element and its corresponding Private Creator Element.
    • Series or Instance Level Attributes contained in includefield parameters shall not be returned.

• Series Resources Search Response Payload

  • For each matching Series, the origin server shall return all Attributes listed in Table 10.6.3-4.
  • In addition, the response shall contain:
  • All other Series Level Attributes passed as match Query Parameters, or Series or Study Level Attributes passed as includefield parameters in the request that are supported by the origin server.
  • If the "includefield" parameter has been specified in the request and its value is "all", include all Series Level Attributes specified as Optional Keys in Section C.6.1.1.4 "Series Level" in PS3.4 that are supported by the Origin Server.
  • If the Target Resource is All Series, then include all Study Level Attributes specified in Section 10.6.3.3.1.
  • Instance level attribute in includefield parameter is not returned.

• Instance Resources Search Response Payload

  • For each matching Instance, the origin server shall return all Attributes listed in Table 10.6.3-5, if present in the Instance.
  • In addition, the response shall contain:
  • All other Instance Level Attributes passed as match parameters, or Study, Series, or Instance Level Attributes passed as includefield parameters that are supported by the origin server.
  • If the Target Resource is All Instances, then include all Study level Attributes specified in Section 10.6.3.3.1.
  • If the Target Resource is All Instances or Study's Instances, then include all Series level Attributes specified in Section 10.6.3.3.2.
  • The response may optionally include the Available Transfer Syntax UID (0008,3002) to describe the Transfer Syntaxes that the origin server can assure will be supported for retrieval of the SOP Instance.

Media Types

The origin server shall support the default and required media types as specified in Table 10.6.4-1.

Notes on Implementation

• Origin server does not need to support all resources at all level. For example, Study level resources instances (/studies/{study}) such as /metadata, /bulkdata, /rendered, /pixeldata or /thumbnail representations are ambiguous and use cases are not clear. Also, it will put heavy burden on server side resource and connection may timeout when dealing with a large CT or MR studies. Same argument applies to Series instances (/studies/{study}/series/{series}).

• Origin server should support capabilities transactions (OPTIONS) for each resources level. It should return proper WADL encoded response (or JSON) for all resource it support at the target resource level and level below. For example, OPTIONS with target resource of /studies/{study} should return all capabilities for Studies, Series and Instance level and related resources (e.g. metadata, bulkdata, thumbnail, pixeldata, etc.) Similarly, if the target is a SOP instance (/studies/{study}/series/{series}/instances/{instance}), it should respond based what we support for the instance level (e.g. DICOM SR instance, rendered to HTML or PDF, Encapsulated PDF as mimetype PDF or Structured Display instance to rendered study).

  • WADL document shall contain one top-level "application" element and it should contain one "resources" element whose "base" attribute value is the base URL for the service. Additionally, the WADL content shall include a "resource" element for the Target Resource specified in the request describing all methods and child resources for the specified resource and each of its children.

  • Success with 304 (not Modified) response should be returned for all standard defined resources that are not supported by an implementation. That means a configuration option should be defined on the origin server either to support or not some resources (don't support render study or study bulkdata).

  • Origin Server support of Retrieve Capabilities transaction should support the following use cases for a client application:

  • PACS Admin needs to configure a DICOMweb client (a viewer) based on capabilities supported by the origin server. This is using Studies resource as target.

  • A DICOMweb Viewer, have logic to identify what capabilities DICOMweb server supports at different resource or resource instance level. This will require each target resource to support capabilities transaction. For example, do the server support rendering Structured Report (SR) in HTML or PDF format? if not it will get the DICOM JSON.

• Since GET call to same target resource is used for search and retrieve, DICOM standard is no longer using QIDO-RS, and WADO-RS is target to distinguish the call type and rout to appropriate handler, then the following logic can be used:

  • Query - is GET with "?" in the URL.
  • Retrieve - is GET with no "?" argument for getting DICOM instance but rest will have additional resource specified like \metadata or \rendered etc.
  • Store - POST can only target two resources "\studies" and "\studies{Study Instance UID}".
  • Capabilities - OPTIONS at any resource or resource instance level. Respond with Success status and code 304.

• There should be an option for any DICOM instance that our proxy retrieves from the remote PACS or the remote DICOMweb origin server, to be added to the storage server database and webservices cache.

• Query result should be ordered and cached on the server side to support limit and offset. Unfortunately, there is no term in the standard that servers the client to supply a transaction UID to link the query with the original search result. In order to utilize caching, the server should use the specific set of parameters used in the query as key for cache lookup.

• Time range or datetime should pay attention to Timezone Offset From UTC (0008,0201) during the query process.

• The server should have a configuration option to limit the number of query response. If the number of results exceeds the maximum supported by the server, the server shall return the maximum supported results and the response shall include the following HTTP/1.1 warning header:
  Warning: 299 {SERVICE}: "The number of results exceeded the maximum supported by the server. Additional results can be requested.

Additional DICOMweb services

Not covered in this document are as follows:

Worklist Web Service (UPS-RS)

Defines a RESTful interface to the unified procedure step service SOP classes defined in Section B.26 "Unified Procedure Step IOD" in PS3.3 and Section CC "Unified Procedure Step Service and SOP Classes (Normative)" in PS3.4, in which UPS behavior is specified.

The following resources are defined:

• Worklist - A collection of Workitems managed by the origin server.
• Workitem - A dataset containing the attributes specified in "UPS Attribute Service Requirements" in PS3.4.
• Subscription - Specifies a subscriber, to whom notifications about changes in the resource's state should be sent.

The URI Templates defined by this service are specified in Table 11.1.1-1.

The Worklist service consists of transactions in Table 11.3-1.

Non-Patient Instance Service (NPI)

Enables a user agent to retrieve, store, and search an origin server for instances that are not related to an individual patient.

The following NPI resources are defined in the standard:

• color-palettes
• defined-procedure-protocols
• hanging-protocols
• implant-templates
• inventories

The following transactions are defined for the above resources:

• Retrieve Capabilities
• Retrieve
• Store

• Search

Storage Commitment Service

This enables a user agent to request the safekeeping of instances on an origin server. It corresponds to the DIMSE Storage Commitment Service Class as defined in Section J "Storage Commitment Service Class (Normative)" in PS3.4 and has the same semantics.

As committing to storage of instances is often a long-running operation on the origin server, the use of this service may be split into two transactions, at the discretion of the origin server: 1. requesting the commitment, and - when the origin server cannot give the result yet - 2. checking for the result, in line with the Asynchronous Request-Reply (ARR) pattern [Ekuan].

The Storage Commitment request shall have the following syntax:

POST SP /commitment-requests/{transactionUID} SP version CRLF 
Accept: 1#media-type CRLF 
*(header-field CRLF) 
CRLF 

Target Resource

/commitment-requests.

Payload

The Result Check Transaction shall have following syntax:

GET SP /commitment-requests/{transactionUID} SP version CRLF 
Accept: 1#media-type CRLF 
*(header-field CRLF) 
CRLF 

See Also

WADO-URI Web Service