DICOM PS3.18 2017c - Web Services

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.

  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:

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.

See Section 6.1.4.

Mapping between IOD and HTTP message parts

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


Responses shall be encoded in the following manner: (see Figure 6.5-1).

The compressed pixel data consists of the compressed bit stream only, and shall not include any Sequence Items and Delimiters from the PS3.5 Encapsulated Pixel Data format.

Compressed pixel data shall be encoded using the application/dicom media type and transfer syntaxes specified in Table 6.1.1.8-2.

The request header field Content-Type is used to indicate the media type of the payload.

If the origin server returns XML or JSON responses that contain bulk data references, the origin server is required to support uncompressed bulk data (application/octet-stream) and must be able to deliver all bulk data in that form (i.e., decompress it from its original form if necessary) unless it is available only in a lossy-compressed format.

The DICOM Media Types supported are defined in Section 6.1.1.8.5.

The Bulk Data Media Types supported are defined in Table 6.1.1.8-1c and Table 6.1.1.8-1d.

The origin server shall support the transfer-syntax and charset media type parameters.

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" [dcm-parameters]

        Specifies that the response can be DICOM Instances encoded in PS3.10 format. If transfer-syntax is not specified in the dcm-parameters the origin server shall use the Explicit VR Little Endian Transfer Syntax "1.2.840.10008.1.2.1" for each Instance (see Section 6.1.1.8).

      • multipart/related; type="application/octet-stream" [dcm-parameters]

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

      • multipart/related; type="{media-type}" [dcm-parameters]

        Specifies that the response can be compressed pixel data encoded using the media types and transfer syntaxes specified in Table 6.1.1.8-3b. See Section 6.1.3.

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; type="image/jpx"; transfer-syntax=1.2.840.10008.1.2.4.92,, multipart/related; type="image/jpx"; transfer-syntax=1.2.840.10008.1.2.4.93, multipart/related; type="image/jpeg"

    • or alternatively, multiple Accept headers:

      • Accept: multipart/related; type="image/jpx"; transfer-syntax=1.2.840.10008.1.2.4.92,

      • Accept: multipart/related; type="image/jpx"; transfer-syntax=1.2.840.10008.1.2.4.93

      • Accept: multipart/related; type="image/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 part in the multipart response represents a DICOM SOP Instance with the following http headers:

    • Content-Type: application/dicom [dcm-parameters]

See Section 6.1.3.

6.5.1.2.2 Bulk Data Response
  • Content-Type:

    • multipart/related; type="application/octet-stream"; boundary={MessageBoundary} [dcm-parameters]

    • multipart/related; type="{media-type}"; boundary={MessageBoundary} [dcm-parameters]

    See Section 6.1.3.

  • 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}

    • an Encapsulated Document (0042,0011) bulk data element from a SOP Instance in the Study encoded in the media type specified in MIME Type of Encapsulated Document (0042,0012) in the Instance with the following header fields:

      • Content-Type: {media-type}

      • 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: {media-type} [dcm-parameters]

      • 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: {media-type} [dcm-parameters]

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

        Note

        Each frame will come in a separate part.

    • all of the compressed frames from a SOP Instance in the Study encoded in a video media type with the following headers:

      • Content-Type: {media-type} [dcm-parameters]

      • Content-Location: {BulkDataURI}

DICOM PS3.18 2017c - Web Services