DICOM PS3.18 2016b - Web Services

6.5 WADO-RS Request/Response
Prev | 6 Data Communication Requirements | Next

## 6.5 WADO-RS Request/Response

The DICOM RESTful Service defines several action types. An implementation shall support all the following six action types:

1. RetrieveStudy

   This action retrieves the set of DICOM instances associated with a given study unique identifier (UID). The response can be DICOM or bulk data depending on the "Accept" type, and is encapsulated in a multipart MIME response.

2. RetrieveSeries

   This action retrieves the set of DICOM instances associated with a given study and series UID. The response can be DICOM or bulk data depending on the "Accept" type, and is encapsulated in a multipart MIME response.

3. RetrieveInstance

   This action retrieves the DICOM instance associated with the given study, series, and SOP Instance UID. The response can be DICOM or bulk data depending on the "Accept" type, and is encapsulated in a multipart MIME response.

4. RetrieveFrames

   This action retrieves the DICOM frames for a given study, series, SOP Instance UID, and frame numbers. The response is pixel data, and encapsulated in a multipart MIME response.

5. RetrieveBulkdata

   This action retrieves the bulk data for a given BulkDataURI. The response is a single bulk data item.

6. RetrieveMetadata

   This action retrieves the DICOM instances presented as the study, series, or instance metadata with the bulk data removed.

WADO-RS requests may contain the following query parameters:

- "accept" The <accept> query parameter is specified in Section 6.1.1.5. The syntax is:

          accept = "accept=" 1#media-type

- "charset" The <character-set> query parameter is specified in Section 6.1.2.2. The syntax is:

          character-set = "charset" = 1#charset

WADO-RS requests shall include an "Accept" header field (see Section 6.1.1.6) specifying the Acceptable Media Types.

WADO-RS requests may optionally support the "Accept-Charset" header field. See Section 6.1.2.3.

DICOM Objects returned shall be PS3.10 binary objects encoded in a requested Transfer Syntax (Explicit VR Little Endian by default) with one message part per DICOM Instance.

Figure 6.5-1. Mapping between IOD and HTTP message parts

Other types of responses will be encoded in the following manner: (see Figure 6.5-1).

- All XML responses shall be encoded as described in the Native DICOM Model defined in PS3.19 with one message part per XML object.

- All JSON responses shall be encoded as a DICOM JSON Model Object as defined in Annex F.

- Uncompressed bulk and pixel data shall be encoded in a Little Endian format using the application/octet-stream media type with one message part per bulk data item.

- Compressed pixel data may be encoded in one of three ways:

  - Single-frame pixel data encoded using a single-frame media type (one message part)

  - Multi-frame pixel data encoded using a single-frame media type (one frame per message part)

  - Multi-frame or video pixel data encoded using a multi-frame media type (multiple frames in one message part)

Compressed pixel data shall be encoded using the following Media Types. Media Types corresponding to several DICOM Transfer Syntax UIDs require a transfer-syntax parameter, as shown in Table 6.5-1, to disambiguate the request.

### Note

If the Transfer Syntax is not specified, then a reversible (lossless) encoding is used.

Table 6.5-1. Media Type Mapping to Transfer Syntax

DICOM Transfer Syntax UID | Media Type and Parameters
--- | ---
Single-frame media types
1.2.840.10008.1.2.4.50 | image/dicom+jpeg; transfer-syntax=1.2.840.10008.1.2.4.50
1.2.840.10008.1.2.4.51 | image/dicom+jpeg; transfer-syntax=1.2.840.10008.1.2.4.51
1.2.840.10008.1.2.4.57 | image/dicom+jpeg; transfer-syntax=1.2.840.10008.1.2.4.57
1.2.840.10008.1.2.4.70 | image/dicom+jpeg
1.2.840.10008.1.2.4.70 | image/dicom+jpeg; transfer-syntax=1.2.840.10008.1.2.4.70
1.2.840.10008.1.2.5 | image/dicom+rle
1.2.840.10008.1.2.5 | image/dicom+rle; transfer-syntax=1.2.840.10008.1.2.5
1.2.840.10008.1.2.4.80 | image/dicom+jpeg-ls
1.2.840.10008.1.2.4.80 | image/dicom+jpeg-ls; transfer-syntax=1.2.840.10008.1.2.4.80
1.2.840.10008.1.2.4.81 | image/dicom+jpeg-ls; transfer-syntax=1.2.840.10008.1.2.4.81
1.2.840.10008.1.2.4.90 | image/dicom+jp2
1.2.840.10008.1.2.4.90 | image/dicom+jp2; transfer-syntax=1.2.840.10008.1.2.4.90
1.2.840.10008.1.2.4.91 | image/dicom+jp2; transfer-syntax=1.2.840.10008.1.2.4.91
1.2.840.10008.1.2.4.92 | image/dicom+jpx
1.2.840.10008.1.2.4.92 | image/dicom+jpx; transfer-syntax=1.2.840.10008.1.2.4.92
1.2.840.10008.1.2.4.93 | image/dicom+jpx; transfer-syntax=1.2.840.10008.1.2.4.93
Multi-frame media types
1.2.840.10008.1.2.4.92 | image/dicom+jpx
1.2.840.10008.1.2.4.92 | image/dicom+jpx; transfer-syntax=1.2.840.10008.1.2.4.92
1.2.840.10008.1.2.4.93 | image/dicom+jpx; transfer-syntax=1.2.840.10008.1.2.4.93
1.2.840.10008.1.2.4.100 | video/mpeg; transfer-syntax=1.2.840.10008.1.2.4.100
1.2.840.10008.1.2.4.101 | video/mpeg; transfer-syntax=1.2.840.10008.1.2.4.101
1.2.840.10008.1.2.4.102 | video/mp4; transfer-syntax=1.2.840.10008.1.2.4.102
1.2.840.10008.1.2.4.103 | video/mp4; transfer-syntax=1.2.840.10008.1.2.4.103

### Note

For the media type image/dicom+jp2 Transfer Syntaxes, 1.2.840.10008.1.2.4.90 and 1.2.840.10008.1.2.4.91, the image does not include the jp2 wrapper.

HTTP Request field Accept is used in the header lines by the client in a HTTP protocol transaction to indicate the data responses that are acceptable from the server. HTTP Response fields Content-Type and parameters are used in the header lines by the server in a HTTP protocol transaction to indicate the type and encoding of data returning to the client. All lines are [RFC822] format headers. All HTTP header fields whose use is not defined by WADO-RS are presumed to have the meaning defined by the HTTP standard.

The server is required to support uncompressed bulk and pixel data (application/octet-stream) and must be able to deliver all bulk data in that form unless it is available only in a lossy-compressed format.

### 6.5.1 WADO-RS - RetrieveStudy

This action retrieves the set of DICOM instances associated with a given study unique identifier (UID). The response can be DICOM or bulk data depending on the "Accept" type, and is encapsulated in a multipart MIME response.

#### 6.5.1.1 Request

The specific Services resource to be used for the RetrieveStudy action shall be as follows:

- Resource

  - {SERVICE}/studies/{StudyInstanceUID}, where

    - {SERVICE} is the base URL for the service. This may be a combination of protocol (either http or https), host, port, and application.

    - {StudyInstanceUID} is the study instance UID for a single study.

- Method

  - GET

- Headers

  - Accept - A comma-separated list of representation schemes, in preference order, which will be accepted by the service in the response to this request. The types allowed for this request header are as follows:

    - multipart/related; type=application/dicom; [transfer-syntax={TransferSyntaxUID}]

      Specifies that the response can be DICOM Instances encoded in PS3.10 format. If transfer-syntax is not specified the server can freely choose which Transfer Syntax to use for each Instance.

    - multipart/related; type=application/octet-stream

      Specifies that the response can be Little Endian uncompressed bulk data.

    - multipart/related; type={MediaType}

      Specifies that the response can be pixel data encoded using a {MediaType} listed in Table 6.5-1 (including parameters).

### Note

An example of a more complicated accept header with multiple transfer syntaxes:

- User is interested in receiving JPEG2000 pixel data in lossless or compressed format but is willing to accept JPEG as well.

  - The Accept request would contain the following comma-separated parameters:

    - Accept: multipart/related=image/dicom+jpx; transfer-syntax=1.2.840.10008.1.2.4.92,, multipart/related=image/dicom+jpx; transfer-syntax=1.2.840.10008.1.2.4.93, multipart/related=image/dicom+jpeg

  - or alternatively, multiple Accept headers:

    - Accept: multipart/related=image/dicom+jpx; transfer-syntax=1.2.840.10008.1.2.4.92,

    - Accept: multipart/related=image/dicom+jpx; transfer-syntax=1.2.840.10008.1.2.4.93

    - Accept: multipart/related=application/dicom+jpeg

#### 6.5.1.2 Response

The Server shall provide the document(s) indicated in the request. In order to parse the bulk data items it is necessary to also retrieve the metadata for the Study.

The Server shall return the document(s), or an error code when the document(s) cannot be returned. If the server cannot convert all of the data to any of the requested media types/Transfer Syntaxes, then an error code shall be returned, either a "Not Acceptable" response if no data is returned or a "Partial Content" response if only some data is returned.

The client can compare the SOP Instance UIDs or BulkDataURIs in the metadata and the message response to determine which bulk data elements have been returned.

All response formats have a media type of multipart/related with a message boundary separator. The response format depends on the Accept header specified in the request.

##### 6.5.1.2.1 DICOM Response

- Content-Type:

  - multipart/related; type=application/dicom; boundary={MessageBoundary}

- The entire multipart response contains every instance for the specified Study that can be converted to one of the requested Transfer Syntaxes.

- Each item in the multipart response represents a DICOM SOP Instance with the following http headers:

  - Content-Type: application/dicom

##### 6.5.1.2.2 Bulk Data Response

- Content-Type:

  - multipart/related; type=application/octet-stream; boundary={MessageBoundary}

  - multipart/related; type={MediaType}; boundary={MessageBoundary}

- The entire multipart response contains all bulk data for the specified Study that can be converted to one of the requested media types.

- Each item in the response is one of:

  - an uncompressed bulk data element encoded in Little Endian binary format with the following headers:

    - Content-Type: application/octet-stream

    - Content-Location: {BulkDataURI}

  - a compressed bulk data element from a SOP Instance in the Study encoded in a single-frame compression {MediaType} with the following headers:

    - Content-Type: {MediaType}

    - Content-Location: {BulkDataURI}

  - a compressed frame from a multi-frame SOP Instance in the Study encoded in a single-frame media type with the following headers:

    - Content-Type: {MediaType}

    - Content-Location: {BulkDataURI}/frames/{FrameNumber}

      ### Note

      Each frame will come in a separate part.

  - a set of compressed frames from a SOP Instance in the Study encoded in a multi-frame media type with the following headers:

    - Content-Type: {MediaType}

    - Content-Location: {BulkDataURI}[/frames/{FrameList}]

      - {FrameList} is a list of frames separated by %2C (comma). It may be omitted if the message part includes all frames for the specified bulk pixel data object.

Prev | Up | Next
6.4.4 Error Codes | Home | 6.5.2 WADO-RS - RetrieveSeries

DICOM PS3.18 2016b - Web Services