DICOM PS3.18 2020b - Web Services

10.4 Retrieve Transaction (Current)
Prev | 10 Studies Service and Resources | Next

## 10.4 Retrieve Transaction

This Transaction uses the GET method to retrieve the Target Resource. 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 rendered Instances as application/jpeg images.

The retrieve transaction supports DICOM, Rendered, and Thumbnail Resources.

### 10.4.1 Request

The request shall have the following syntax:

    GET SP "/" {/resource} {?parameter*} SP versionCRLF

    Accept: 1#media-type CRLF

    *(header-fieldCRLF)

    CRLF

Where parameter is one of the Query Parameters defined for the Target Resource in Section 10.4.1.2.

#### 10.4.1.1 Target Resources

##### 10.4.1.1.1 DICOM Resources

Table 10.4.1-1 defines the DICOM resources that may be retrieved.

Table 10.4.1-1. Retrieve Transaction DICOM Resources

Resource | URI Template
--- | ---
Study |
    /studies/{study}
Series |
    /studies/{study}/series/{series}
Instance |
    /studies/{study}/series/{series}/instances/{instance}
Frames |
    /studies/{study}/series/{series}/instances/{instance}/frames/{frames}
Bulkdata |
    /{/bulkdata}

##### 10.4.1.1.2 Metadata Resources

Table 10.4.1-2 defines the resources used to retrieve the metadata contained in Instances.

Table 10.4.1-2. Retrieve Transaction Metadata Resources

Resource | URI Template
--- | ---
Study Metadata |
    /studies/{study}/metadata
Series Metadata |
    /studies/{study}/series/{series}/metadata
Instance Metadata |
    /studies/{study}/series/{series}/instances/{instance}/metadata

The Metadata Resources are used to retrieve the DICOM instances without retrieving Bulkdata. The Metadata returned for a study, series, or instance resource includes all Attributes in the resource. For Data Elements having a Value Representation (VR) of DS, FL, FD, IS, LT, OB, OD, OF, OL, OV, OW, SL, SS, ST, SV, UC, UL, UN, US, UT and UV, the origin server is permitted to replace the Value Field of the Data Element with a Bulkdata URI. The user agent can use the Bulkdata URI to retrieve the Bulkdata.

##### 10.4.1.1.3 Rendered Resources

A Retrieve Transaction on a Rendered Resource will return a response that contains 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.

A Rendered Resource contains one or more rendered representations, i.e., in a Rendered Media type, of its parent DICOM Resource. Table 10.4.1-3 shows the Rendered Resources supported by the Retrieve transaction along with their associated URI templates.

Table 10.4.1-3. Retrieve Transaction Rendered Resources

Resource | URI Template
--- | ---
Rendered Study |
    /studies/{study}/rendered
Rendered Series |
    /studies/{study}/series/{series}/rendered
Rendered Instance |
    /studies/{study}/series/{series}/instances/{instance}/rendered
Rendered Frames |
    /studies/{study}/series/{series}/instances/{instance}/frames/{frames}/rendered

The origin server shall be able to render all valid Instances of the Composite SOP classes for which conformance is claimed, e.g., origin server shall be able to render all Photometric Interpretations that are defined in the IOD for that SOP class.

The content type of the response payload shall be a Rendered Media Type. See Section 8.7.4.

##### 10.4.1.1.4 Thumbnail Resources

A Retrieve Transaction on a Thumbnail resource will return a response that contains a rendered representation of its parent DICOM Resource.

Table 10.4.1-4 shows the Thumbnail resources supported by the Retrieve transaction along with their associated URI templates.

Table 10.4.1-4. Retrieve Transaction Thumbnail Resources

Resource | URI Template
--- | ---
Study Thumbnail |
    /studies/{study}/thumbnail
Series Thumbnail |
    /studies/{study}/series/{series}/thumbnail
Instance Thumbnail |
    /studies/{study}/series/{series}/instances/{instance}/thumbnail
Frame Thumbnail |
    /studies/{study}/series/{series}/instances/{instance}/frames/{frames}/thumbnail

The representation returned in the response to a Retrieve Thumbnail resource request shall be in a Rendered Media Type. The Thumbnail shall not contain any Patient Identifying Information. Only a single image shall be returned.

If the origin server supports any of the Thumbnail resources, it shall support all of them.

The origin server will determine what constitutes a meaningful representation.

The origin server may return a redirection response (HTTP status code 302) to a rendered resource instead of returning a rendered image.

There is no requirement that Thumbnail resources be related to any Icon Image Sequence (0088,0200) encoded in Instances or returned in query responses.

#### 10.4.1.2 Query Parameters

The origin server shall support Query Parameters as required in Table 10.4.1-5.

The user agent shall supply in the request Query Parameters as required in Table 10.4.1-5.

Table 10.4.1-5. Query Parameters by Resource

Key | Resource Category | Usage | Section
--- | --- | --- | ---
User Agent | Origin Server
accept | All | O | M | Section 8.3.3.1
charset | Text | O | M | Section 8.3.3.2
annotation | Rendered | O | M | Section 8.3.5.1.1
quality | Rendered | O | M | Section 8.3.5.1.2
viewport | Rendered | O | M | Section 8.3.5.1.3
Thumbnail | O | O
window | Rendered | O | M | Section 8.3.5.1.4
iccprofile | Rendered | O | O | Section 8.3.5.1.5

#### 10.4.1.3 Request Header Fields

The origin server shall support header fields as required in Table 10.4.1-6 in the request.

The user agent shall supply in the request header fields as required in Table 10.4.1-6.

Table 10.4.1-6. Request Header Fields

Name | Values | Usage | Description
--- | --- | --- | ---
User Agent | Origin Server
Accept | media-type | M | M | The Acceptable Media Types of the response payload
Accept-Charset | charset | O | M | The Acceptable Character Sets of the response payload

See also Section 8.4.

#### 10.4.1.4 Request Payload

The request shall have no payload.

Prev | Up | Next
10.3 Transactions Overview | Home | 10.4.2 Behavior

DICOM PS3.18 2020b - Web Services