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 bulk data URL. The response is a single bulk data item.

  6. RetrieveMetadata

    This action retrieves the DICOM instances presented as the full study metadata with the bulk data removed. The response is XML encoded metadata for the DICOM attributes as defined in PS3.19.

All responses will be HTTP multipart messages.

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.

Mapping between IOD and HTTP message parts

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).

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 XML 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 bulk data URLs in the metadata and the message response to determine which bulk data elements have been returned.

All response formats have a content 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: {BulkDataURL}

    • 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: {BulkDataURL}

    • 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: {BulkDataURL}/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: {BulkDataURL}[/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.

6.5.2 WADO-RS - 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.

6.5.2.1 Request

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

  • Resource

    • {SERVICE}/studies/{StudyInstanceUID}/series/{SeriesInstanceUID}, 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.

      • {SeriesInstanceUID} is the series instance UID for a single series.

  • 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).

6.5.2.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 XML 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 bulk data URLs in the metadata and the message response to determine which bulk data elements have been returned.

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

6.5.2.2.1 DICOM Response
  • Content-Type:

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

  • The entire multipart response contains every instance for the specified Series 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.2.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 Series 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: {BulkDataURL}

    • a compressed bulk data element from a SOP Instance in the Series encoded in a single-frame media type with the following headers:

      • Content-Type: {MediaType}

      • Content-Location: {BulkDataURL}

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

      • Content-Type: {MediaType}

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

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

      • Content-Type: {MediaType}

      • Content-Location: {BulkDataURL}[/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.

6.5.3 WADO-RS - 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.

6.5.3.1 Request

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

  • Resource

    • {SERVICE}/studies/{StudyInstanceUID}/series/{SeriesInstanceUID}/instances/{SOPInstanceUID}, 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.

      • {SeriesInstanceUID} is the series instance UID for a single series.

      • {SOPInstanceUID} is the SOP Instance UID for a single SOP Instance.

  • 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).

6.5.3.2 Response

The Server shall provide either a single DICOM PS3.10 object for the SOP Instance or one or more bulk data items. In order to parse the bulk data items it is necessary to also retrieve the XML 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 bulk data to any of the requested media types, 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 bulk data URLs in the metadata and the message response to determine which bulk data elements have been returned.

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

6.5.3.2.1 DICOM Response
  • Content-Type:

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

  • The multipart response contains a single item representing the specified DICOM SOP Instance with the following http headers:

    • Content-Type: application/dicom

6.5.3.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 Instance 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: {BulkDataURL}

    • a compressed bulk data element from a SOP Instance encoded in a single-frame media type with the following headers:

      • Content-Type: {MediaType}

      • Content-Location: {BulkDataURL}

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

      • Content-Type: {MediaType}

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

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

      • Content-Type: {MediaType}

      • Content-Location: {BulkDataURL}[/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.

6.5.4 WADO-RS - RetrieveFrames

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

6.5.4.1 Request

The specific Services resources to be used for the RetrieveFrames action shall be as follows:

  • Resource

    • {SERVICE}/studies/{StudyInstanceUID}/series/{SeriesInstanceUID}/instances/{SOPInstanceUID}/frames/{FrameList}, 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.

      • {SeriesInstanceUID} is the series instance UID for a single series.

      • {SOPInstanceUID} is the SOP Instance UID for a single SOP Instance.

      • {FrameList} is a comma or %2C separated list of one or more non duplicate frame numbers. These may be in any order (e.g., ../frames/1,2,4,3).

  • Method

    • GET

  • Headers

    • Accept

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

        Specifies that the response can be Little Endian uncompressed pixel data

      • multipart/related; type={MediaType}

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

6.5.4.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 XML 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 encode the pixel data using any of the requested media types, then an error status shall be returned.

All response formats has a content type of multipart/related with a message boundary separator.

6.5.4.2.1 Pixel Data Response
  • Content-Type:

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

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

  • The entire multipart response contains all requested Frames for the specified Instance.

  • Each item in the response is one of:

    • an uncompressed frame encoded in Little Endian binary format with the following headers:

      • Content-Type: application/octet-stream

      • Content-Location: {BulkDataURL}[/frames/{FrameNumber}]

    • a compressed frame encoded in a single-frame media type with the following headers:

      • Content-Type: {MediaType}

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

    • a set of compressed frames encoded in a multi-frame media type with the following headers:

      • Content-Type: {MediaType}

      • Content-Location: {BulkDataURL}[/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.

  • The frames will be returned in the order specified by the Frame List.

6.5.5 WADO-RS - RetrieveBulkdata

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

6.5.5.1 Request

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

  • Resource

    • {BulkDataURL}, where

      • {BulkDataURL} is the URL of a bulk data element. This may be the URL attribute of a BulkData element from a DICOM PS3.19 XML file received in response to a WADO-RS RetrieveMetadataRequest.

      • The server shall always return the same bulk data for a specified BulkData URL if the data is available.

      • If the resource specified by the BulkData URL is not available, the server shall return:

        • 404 - Not Found, if the server expects to be able to return the resource again in the future

        • 410 - Gone, if the server does not expect the resource to be valid in the future

      • The server determines the period of time a BulkData URL resource is available.

  • Method

    • GET

  • Headers

    • Accept

      • 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).

    • Range

      • See RFC 2616 Section 14.35. If omitted in the request the server shall return the entire bulk data object.

6.5.5.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 XML 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 encode the pixel data using any of the requested media types, then an error status shall be returned.

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

6.5.5.2.1 Bulk Data Response
  • Content-Type:

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

  • The single 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: {BulkDataURL}

    • a compressed bulk data element from a SOP Instance encoded in a single-frame media type with the following headers:

      • Content-Type: {MediaType}

      • Content-Location: {BulkDataURL}

  • If the Range header is specified in the request, the server shall return only the specified bytes of the bulk data object. See RFC 2616 Section 14.35.

6.5.6 WADO-RS - RetrieveMetadata

This action retrieves the DICOM instances presented as the full study metadata with the bulk data removed. The response is XML encoded metadata for the DICOM attributes as defined in PS3.19.

The full study metadata includes all attributes of the study; however, a RESTful Service is permitted to replace the Value Field of an attribute with a BulkDataURL for attributes with Value Representations (VR) of FL, FD, IS, LT, OB, OD, OF, OW, SL, SS, ST, UL, UN, US, and UT. The client can use the BulkDataURL with the RetrieveBulkData action to retrieve the original Value Field of that attribute.

Note

  1. The server is not required to replace any attribute with a BulkDataURL; this is intended to allow the server to provide clients with metadata of a reasonably small size by leaving out large data Value Fields.

  2. Attributes with binary Value Fields are encoded as XML Base64 binary values.

  3. Some DICOM instances, such as SR documents, may be entirely described in the metadata.

6.5.6.1 Request

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

  • Resource

    • {SERVICE}/studies/{StudyInstanceUID}/metadata, 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

      • multipart/related; type=application/dicom+xml

        Specifies that the response should be WADO XML.

6.5.6.2 Response

The Server shall provide the document(s) indicated in the request. The Server shall return the document(s) or an error code when the document(s) could not be returned.

The response format has a content type of application/dicom+xml as described in the Native DICOM Model defined in PS3.19 and must include the URL attribute for each BulkData element.

6.5.6.2.1 Metadata Response
  • Content-Type:

    • multipart/related; type=application/dicom+xml

  • The entire multipart response contains all XML metadata for the specified Study.

  • Each item in the response is the XML encoded metadata for an Instance with the following http headers:

    • Content-Type: application/dicom+xml; transfer-syntax={TransferSyntaxUID}

      Where {TransferSyntaxUID} is the UID of the DICOM Transfer Syntax used to encode the inline binary data in the XML metadata.

Note

The metadata is consistent with the characteristics of the bulk data on the server. If bulk data is requested using specified Transfer Syntaxes or media types, it is possible that the bulk data retrieved may be inconsistent with the metadata. For example, for a Study whose DICOM Tag (0028,2110) "LossyImageCompression" is set to "00", indicating no lossy compression, calling RetrieveStudy and requesting a lossy compression media type will provide pixel data that is inconsistent with the metadata. It is the responsibility of the client to deal with these inconsistencies appropriately.

6.5.7 Error Codes

The following error codes are defined and 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.5-2. Error Codes

Client Error Code

Client Error Name

Error Situation

206

Partial Content

Accept type, Transfer Syntax or decompression method supported for some but not all requested content.

400

Bad Request

Malformed resource

404

Not Found

Specified resource does not exist

406

Not Acceptable

Accept type, Transfer Syntax or decompression method not supported

410

Gone

Specified resource was deleted

503

Busy

Service is unavailable