DICOM PS3.18 2017b - Web Services

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)

    - 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
{BulkDataURI} | 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="application/dicom+json">
    			<option value="multipart/related; type=application/dicom+xml" />
    			<option value="application/dicom+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/dicom+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/dicom+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 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 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

DICOM PS3.18 2017b - Web Services