6.8 RS Capabilities Service

6.8 RS Capabilities Service
Prev	6 Data Communication Requirements	Next

DICOM RS Capabilities Service defines a single transaction type which shall be supported by all implementations

RetrieveCapabilities

This transaction retrieves the parameters for services supported by the server.

6.8.1 Retrieve Capabilities

6.8.1.1 Request Message

The Retrieve Server Options transaction can be requested for the following resources:

{+SERVICE}/{InformationEntity*}
- where {+SERVICE} is the base URL for the service. This may be a combination of protocol (either http or https), host, port, and application.
- where {InformationEntity} is the path to a defined DICOM RESTful service resource, such as:
  - WADO-RS (see 6.5.1, 6.5.2, 6.5.3, 6.5.4, 6.5.5, 6.5.6)
  - STOW-RS (see 6.6.1)
  - QIDO-RS (see 6.7.1)
  - UPS-RS (see 6.9.1, 6.9.2, 6.9.3, 6.9.4, 6.9.5, 6.9.6, 6.9.7, 6.9.8, 6.9.9)

6.8.1.1.1 Method = OPTIONS

The Retrieve Server Options Service request messages use the OPTIONS method.

6.8.1.1.2 Header Fields

The Retrieve Server Options Service request messages can include the following header fields:

Accept:
- application/vnd.sun.wadl+xml
- application/json

6.8.1.2 Response message

All responses are http single part messages. A successful response will return a Web Application Description Language (WADL) document encoded in a Media Type consistent with the Accept header of the request.

The WADL document shall contain one top-level "application" element.

The "application" element shall contain one "resources" element whose "base" attribute value is {SERVICE}, where {SERVICE} is the base URL for the service. This may be a combination of protocol (either http or https), host, port, and application.

Additionally, the WADL content shall include a "resource" element for the resource specified in the request (see 6.8.1.1) describing all methods (see 6.8.1.2.2.2 for description and examples) and child resources (see 6.8.1.2.2.1 for description and examples) for the specified resource and each of its children.

6.8.1.2.1 Resources

The full WADL resource tree follows directly and unambiguously from the RESTful resource endpoints defined in 6.5, 6.6, 6.7 and 6.9.

For informative purposes, the full resource tree and the methods defined for each resource are described in Table 6.8-1.

Table 6.8-1. Resources and Methods

Resource	Methods supported (excluding RetrieveCapabilities)	Reference
{+SERVICE}	N/A	N/A
studies	SearchForStudies StoreInstances	6.8.1.2.2.3 6.8.1.2.2.2
{StudyInstanceUID}	RetrieveStudy StoreStudyInstances	6.8.1.2.2.1 6.8.1.2.2.3
metadata	RetrieveStudyMetadata	6.8.1.2.2.1
series	SearchForStudySeries	6.8.1.2.2.3
{SeriesInstanceUID}	RetrieveSeries	6.8.1.2.2.1
metadata	RetrieveSeriesMetadata	6.8.1.2.2.1
instances	SearchForStudySeriesInstances	6.8.1.2.2.3
{SOPInstanceUID}	RetrieveInstance	6.8.1.2.2.1
metadata	RetrieveInstanceMetadata	6.8.1.2.2.1
frames	N/A	N/A
{framelist}	RetrieveFrames	6.8.1.2.2.1
instances	SearchForStudyInstances	6.8.1.2.2.3
series	SearchForSeries	6.8.1.2.2.3
{SeriesInstanceUID}	N/A	N/A
{instances}	SearchForInstances	6.8.1.2.2.3
instances	SearchForInstances	6.8.1.2.2.3
{BulkDataURL}	RetrieveBulkData	6.8.1.2.2.1
workitems	SearchForUPS CreateUPS	6.8.1.2.2.3 6.8.1.2.2.2
{UPSInstanceUID}	RetrieveUPS UpdateUPS	6.8.1.2.2.1 6.8.1.2.2.4
state	ChangeUPSState	6.8.1.2.2.4
cancelrequest	RequestUPSCancel	6.8.1.2.2.4
subscribers	N/A	N/A
{AETitle}	CreateSubscription DeleteSubscription	6.8.1.2.2.5 6.8.1.2.2.5
1.2.840.10008.5.1.4.34.5	N/A	N/A
subscribers	N/A	N/A
{AETitle}	CreateSubscription DeleteSubscription	6.8.1.2.2.5 6.8.1.2.2.5
suspend	SuspendGlobalSubscription	6.8.1.2.2.5
1.2.840.10008.5.1.4.34.5.1	N/A	N/A
subscribers	N/A	N/A
{AETitle}	CreateSubscription DeleteSubscription	6.8.1.2.2.5 6.8.1.2.2.5
suspend	SuspendGlobalSubscription	6.8.1.2.2.5

6.8.1.2.2 Methods

6.8.1.2.2.1 Retrieve Methods

The Retrieve methods define the capabilities of a WADO-RS resource (see 6.5) or a RetrieveUPS resource (see 6.9.4).

The Retrieve methods shall contain the following attributes:

A "name" attribute with a value of "GET"
An "id" attribute with a value of "RetrieveStudy", "RetrieveSeries", "RetrieveInstance", "RetrieveBulkData", "RetrieveFrames", "RetrieveStudyMetadata", "RetrieveSeriesMetadata", "RetrieveInstanceMetadata" or "RetrieveUPS"

The Retrieve methods shall contain a "request" element with "param" elements documenting the following:

supported Accept header values
- if the same Media Type is supported with multiple Transfer Syntaxes there should be one entry for each combination of Media Type and Transfer Syntax

The Retrieve methods shall contain one or more "response" elements documenting the following:

supported Status Codes
Media Types returned for each Status Code (if applicable)
- if the same Media Type is supported with multiple Transfer Syntaxes there should be one entry for each combination of Media Type and Transfer Syntax

Note

More than one Status Code can be described by a single "response" element.

Example:

<method name="GET" id="RetrieveStudies">
	<request>
		<param name="Accept" style="header" default="multipart/related; type=application/dicom">
			<option value="multipart/related; type=application/dicom" />
			<option value="multipart/related; type=application/dicom";
			        transfer-syntax=1.2.840.10008.1.2 />
			<option value="multipart/related; type=application/dicom";
			        transfer-syntax=1.2.840.10008.1.2.1 />
			<option value="multipart/related; type=application/octet-stream" />
			<option value="multipart/related; type=image/dicom+jpx" />
			<option value="multipart/related; type=image/dicom+jpx;
			        transfer-syntax=1.2.840.10008.1.2.4.92" />
			<option value="multipart/related; type= video/mpeg;
			        transfer-syntax=1.2.840.10008.1.2.4.100" />
		</param>
	</request>
	<response status="200,206">
		<representation mediaType="multipart/related; type=application/dicom";
		                transfer-syntax=1.2.840.10008.1.2 />
		<representation mediaType="multipart/related; type=application/dicom";
		                transfer-syntax=1.2.840.10008.1.2.1 />
		<representation mediaType="multipart/related; type=application/octet-stream" />
		<representation mediaType="multipart/related; type= image/dicom+jpx" />
		<representation mediaType="multipart/related; type= image/dicom+jpx;
		                transfer-syntax=1.2.840.10008.1.2.4.92" />
		<representation mediaType="multipart/related; type= video/mpeg;
		                transfer-syntax=1.2.840.10008.1.2.4.100" />
	</response>
	<response status="400 404 406 410 503" />
</method>

6.8.1.2.2.2 Store Methods

The Store methods define the capabilities of a STOW-RS resource (see 6.6) or a CreateUPS resource (see 6.9.1).

The Store methods shall contain the following attributes:

A "name" attribute with a value of "POST"
An "id" attribute with a value of "StoreInstances", "StoreStudyInstances" or "CreateUPS"

The Store methods shall contain a "request" element with "param" elements documenting the following:

supported Accept header values
supported Representations
- if the same Media Type is supported with multiple Transfer Syntaxes there should be one entry for each combination of Media Type and Transfer Syntax

The Store methods shall contain one or more "response" elements documenting the following:

supported Status Codes
Media Types returned for each Status Code (if applicable)
Headers returned for each Status Code

Note

More than one Status Code can be described by a single "response" element.

Example:

<method name="GET" id="StoreInstances">
	<request>
		<param name="Accept" style="header" default="application/dicom+xml">
			<option value="application/dicom+xml" />
		</param>
		<representation mediaType="multipart/related; type=application/dicom" />
		<representation mediaType="multipart/related; type=application/dicom;
		                transfer-syntax=1.2.840.10008.1.2" />
		<representation mediaType="multipart/related; type=application/dicom; 
		                transfer-syntax=1.2.840.10008.1.2.1" />
		<representation mediaType="multipart/related; type=application/dicom+xml" />
		<representation mediaType="multipart/related; type=application/dicom+xml;
		                transfer-syntax=1.2.840.10008.1.2" />
		<representation mediaType="multipart/related; type=application/dicom+xml;
						transfer-syntax=1.2.840.10008.1.2.1" />
		<representation mediaType="multipart/related; type=application/dicom+xml;
		                transfer-syntax=1.2.840.10008.1.2.4.92" />
		<representation mediaType="multipart/related; type=application/dicom+xml;
		                transfer-syntax=1.2.840.10008.1.2.4.100" />
	</request>
	<response status="200" />
	<response status="202,409">
		<representation mediaType="application/dicom+xml" />
	</response>
	<response status="400,401,403,503" />
</method>

6.8.1.2.2.3 Search Methods

The Search methods define the capabilities of a QIDO-RS resource (see 6.7) or a SearchForUPS resource (see 6.9.3).

The Search methods shall contain the following attributes:

A "name" attribute with a value of "GET"
An "id" attribute with a value of "SearchForStudies", "SearchForStudySeries", "SearchForSeries", "SearchForStudySeriesInstances", "SearchForStudyInstances", "SearchForSeriesInstances", "SearchForInstances" or "SearchForUPS"

The Search methods shall contain a "request" element with "param" elements documenting the following:

supported Accept header values
support for the Cache-control header
support of "limit", "offset" and "fuzzymatching" query parameters
supported search parameters (both tag and keyword variants shall be listed)
supported options for the "includefield" parameter (both tag and keyword variants shall be listed)

The Search methods shall contain one or more "response" elements documenting the following:

supported Status Codes
returned "header" parameters, including use of "warning headers"
Media Types returned for each Status Code (if applicable)

Note

More than one Status Code can be described by a single "response" element.

Example:

<method name="GET" id="SearchForStudies">
	<request>
		<param name="Accept" style="header" default="multipart/related; type=application/dicom+xml">
			<option value="multipart/related; type=application/dicom+xml" />
			<option value="application/json" />
		</param>
		<param name="Cache-control" style="header">
			<option value="no-cache" />
		</param>
		<param name="limit" style="query" />
		<param name="offset" style="query" />
		<param name="fuzzymatching" style="query" />
		<param name="StudyDate" style="query" />
		<param name="00080020" style="query" />
		<param name="StudyTime" style="query" />
		<param name="00080030" style="query" />
		…
		<param name="includefield" style="query" repeating="true" />
		<option value="all" />
		<option value="00081049" />
		<option value="PhysiciansOfRecordIdentificationSequence" />
		<option value="00081060" />
		<option value="NameOfPhysiciansReadingStudy" />
		…
	</param>
</request>
<response status="200">
	<representation mediaType="multipart/related; type=application/dicom+xml" />
	<representation mediaType="application/json" />
</response>
<response status="400 401 403 413 503" />
</method>

6.8.1.2.2.4 Update Methods

The Update methods define the capabilities of an UpdateUPS, a ChangeUPSState or a RequestUPSCancellation resource (see 6.9.2).

The Update methods shall contain the following attributes:

A "name" attribute with a value of "POST" for UpdateUPS and RequestUPSCancel
A "name" attribute with a value of "PUT" for ChangeUPSState
An "id" attribute with a value of "UpdateUPS", "ChangeUPSState" or "RequestUPSCancellation"

The Update methods shall contain a "request" element with "param" elements documenting the following:

supported Representations

The Update methods shall contain one or more "response" elements documenting the following:

supported Status Codes
Headers returned for each Status Code

Note

More than one Status Code can be described by a single "response" element.

Example:

<method name="POST" id="UpdateUPS">
  <request>
    <representation mediaType="application/dicom+xml" />
    <representation mediaType="application/json" />
  </request>
  <response status="200">
    <param name="Warning" style="header" fixed="299 {+SERVICE}: The UPS was created with modifications." />
    <param name="Warning" style="header" fixed="299 {+SERVICE}: Requested optional Attributes are not supported." />
  </response>
  <response status="409">
    <param name="Warning" style="header" fixed="299 {+SERVICE}: The Transaction UID is missing." />
    <param name="Warning" style="header" fixed="299 {+SERVICE}: The Transaction UID is incorrect." />
    <param name="Warning" style="header" fixed="299 {+SERVICE}: The submitted request is inconsistent
                                                                with the current state of the UPS Instance." />
  </response>
  <response status="400 401 403 404 503" />
</method>

6.8.1.2.2.5 Subscribe Methods

The Subscribe methods define the capabilities of a CreateSubscription, a SuspendGlobalSubscription or a DeleteSubscription resource (see 6.9.7, 6.9.8 and 6.9.9).

The Subscribe methods shall contain the following attributes:

A "name" attribute with a value of "POST" for CreateSubscription and SuspendGlobalSubscription
A "name" attribute with a value of "DELETE" for DeleteSubscription
An "id" attribute with a value of "CreateSubscription", "SuspendGlobalSubscription" or "DeleteSubscription"

The Subscribe methods shall contain a "request" element with "param" elements documenting the following:

supported Representations

The Subscribe methods shall contain one or more "response" elements documenting the following:

supported Status Codes
Headers returned for each Status Code

Note

More than one Status Code can be described by a single "response" element.

Example:

<method name="POST" id="CreateSubscription">
  <request>
    <param name="deletionlock" style="query" default="false">
      <option value="true" />
      <option value="false" />
    </param>
  </request>
  <response status="201">
    <param name="Warning" style="header" fixed="299 {+SERVICE}: Deletion Lock not granted." />
   </response>
  <response status="403">
    <param name="Warning" style="header" fixed="299 {+SERVICE}: The Origin-Server does not support
                                                                Global Subscription Filtering." />
  </response>
  <response status="400 401 404 409 503" />
</method>

6.8.1.3 Status Codes

Table 6.8-2 lists the HTTP/1.1 status codes that shall be used to report any of the associated error and warning situations. Other error codes may be present for other error and warning situations.

Table 6.8-2. Server Options HTTP/1.1 Status Codes

Code	Name	Description
Success
200	OK	The query completed and any matching results are returned in the message body.
Failure
400	Bad Request	The Server Options Provider was unable to perform the query because the Service Provider cannot understand the query component.
401	Unauthorized	The Server Options Provider refused to perform the query because the client is not authenticated.
403	Forbidden	The Server Options Provider understood the request, but is refusing to perform the query (e.g., an authenticated user with insufficient privileges).
503	Busy	Service is unavailable.

Prev	Up	Next
6.7 QIDO-RS Request/Response	Home	6.9 UPS-RS Worklist Service