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)

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 and 6.7.

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 StoreInstances – specified Study	6.8.1.2.2.1 6.8.1.2.2.3
metadata	RetrieveMetadata – Study	6.8.1.2.2.1
series	SearchForSeries	6.8.1.2.2.3
{SeriesInstanceUID}	RetrieveSeries	6.8.1.2.2.1
metadata	RetrieveMetadata – Series	6.8.1.2.2.1
instances	SearchForInstances	6.8.1.2.2.3
{SOPInstanceUID}	RetrieveInstance	6.8.1.2.2.1
metadata	RetrieveMetadata – Instance	6.8.1.2.2.1
frames	N/A	N/A
{framelist}	RetrieveFrames	6.8.1.2.2.1
instances	SearchForInstances – no specified Series	6.8.1.2.2.3
series	SearchForSeries – no specified Study	6.8.1.2.2.3
{SeriesInstanceUID}	N/A	N/A
{instances}	SearchForInstances – no specified Study	6.8.1.2.2.3
instances	SearchForInstances – no specified Study or Series	6.8.1.2.2.3
{BulkDataURL}	RetrieveBulkData	6.8.1.2.2.1

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

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" or "RetrieveInstanceMetadata" depending on the full resource path

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

The Store methods shall contain the following attributes:

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

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

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" or "SearchForInstances" depending on the level of the parent resource

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.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	7 Persistent Object Types