DICOM PS3.18 2021d - 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.

### 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 Instance Resources

Instance Resources (defined in Table 10.4.1-1 are used to retrieve Instances.

Retrieving a Series Instances resource retrieves all the individual Instances contained in the Series. Retrieving a Study Instances resource retrieves all the individual Instances contained in all the Series.

Table 10.4.1-1. Retrieve Transaction Instance Resources

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

### Note

Bulkdata and Frames were previously listed in this table. Bulkdata is addressed in Section 10.4.1.1.5 and Frames data is addressed in Section 10.4.1.1.6.

##### 10.4.1.1.2 Metadata Resources

Metadata Resources (defined in Table 10.4.1-2 are used to retrieve the metadata of Instances without retrieving Bulkdata.

Retrieving a Series Metadata resource retrieves all the metadata for all individual Instances contained in the Series. Retrieving a Study Metadata resource retrieves all the metadata for all individual Instances contained in all the Series.

### Note

An implementation interested in just study level or series level metadata, rather than instance level metadata for all instances, would be better served by using the Search Transaction on the All Studies or Study’s Series resources, matching against the Study Instance UID and using &includefield to specify the metadata of interest (see Section 10.6.1.2).

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

##### 10.4.1.1.3 Rendered Resources

Rendered Resources (defined in Table 10.4.1-3) are used to retrieve 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 exposes one or more rendered representations, i.e., in a Rendered Media type, of its parent DICOM Resource.

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

##### 10.4.1.1.4 Thumbnail Resources

Thumbnail resources (defined in Table 10.4.1-4 are used to retrieve a rendered representation appropriate to stand for its parent DICOM Resource.

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

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

##### 10.4.1.1.5 Bulkdata Resources

Bulkdata resources (defined in Table 10.4.1.5-1 are used to retrieve data elements (typically containing large data, such as Pixel Data) extracted from DICOM Instances.

Table 10.4.1.5-1. Retrieve Transaction Bulkdata Resources

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

### Note

1. Bulkdata resources that contain pixel data can be retrieved equivalently as described in Section 10.4.1.1.6.

2. Refer to Section Section 10.4.1.1.6 for URI templates for Bulkdata consisting of Frame Pixel Data.

##### 10.4.1.1.6 Pixel Data Resources

Pixel Data resources (defined in Table 10.4.1.6-1 are used to retrieve data elements containing top-level pixel data from DICOM Instances.

Pixel data is a subset of bulkdata. The Pixel Data resources provide a convenient method to access that specific subset.

Table 10.4.1.6-1. Retrieve Transaction Pixel Data Resources

Resource | URI Template
--- | ---
Study Pixel Data |
    /studies/{study}/pixeldata
Series Pixel Data |
    /studies/{study}/series/{series}/pixeldata
Instance Pixel Data |
    /studies/{study}/series/{series}/instances/{instance}/pixeldata
Frame Pixel Data |
    /studies/{study}/series/{series}/instances/{instance}/frames/{frames}

### Note

1. Frame Pixel Data is inherently pixel data so a /pixeldata subresource is not needed in the URI Template.

2. The Frame Pixel Data resource originally appeared in Table 10.4.1-1.

#### 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 | Resources | Usage | Section
--- | --- | --- | ---
User Agent | Origin Server
accept | All Resources | O | M | Section 8.3.3.1
charset | Metadata Resources | O | M | Section 8.3.3.2
annotation | Rendered Resources | O | M | Section 8.3.5.1.1
quality | Rendered Resources | O | M | Section 8.3.5.1.2
viewport | Rendered Resources | O | M | Section 8.3.5.1.3
Thumbnail Resources | O | O
window | Rendered Resources | O | M | Section 8.3.5.1.4
iccprofile | Rendered Resources | O | O | Section 8.3.5.1.5

#### 10.4.1.3 Request Header Fields

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

The user agent shall supply 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 See Section 10.4.4 for media types corresponding to each set of target resources defined in Section 10.4.1.1.
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 2021d - Web Services