6.8 RS Capabilities Service
Prev | 6 Data Communication Requirements | Next

## 6.8 RS Capabilities Service

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

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