DICOM PS3.18 2016b - Web Services

6 Data Communication Requirements
Prev |  | Next

# 6 Data Communication Requirements

DICOM Web Services use the HTTP and HTTPS protocols as its transport medium. Web Services supports versions 1.0, 1.1 and 2 of the protocol. If an origin server supports version 2, it shall also support version 1.1. If an origin server supports version 1.1, it shall also support version 1.0.

It is recommended that user agents that want to use HTTP/2 first initiate an HTTP/1.1 connection to the origin server and then upgrade to HTTP/2. If the upgrade fails then the user agent can still use the HTTP/1.1 connection. [RFC7540] Section 3 explains how to initiate HTTP/2 connections.

## 6.1 Interaction

Figure 6-1. Interaction Diagram

The interaction shall be as shown in Figure 6-1.

Multiple communications modes are possible:

- URI based using HTTP Get: WADO-URI request

- Web Services (WS) using HTTP Post: WADO-WS, either:

  1. DICOM Requester (Retrieve Imaging Document Set)

  2. Rendered Requester (Retrieve Rendered Imaging Document Set)

  3. Metadata Requester (Retrieve Imaging Document Set Metadata)

- RESTful Services (RS) using HTTP Get: WADO-RS, either:

  1. DICOM Requester (Retrieve Study, Series, or Instance DICOM Objects)

  2. Frame Pixel Data Requester (Retrieve Instance Frame Pixel Data)

  3. Bulk Data Requester (Retrieve Study, Series, Instance Bulk Data)

  4. Metadata Requester (Retrieve Study, Series, Instance Metadata)

- RESTful Services (RS) using HTTP Get: QIDO-RS:

  1. Query Requester (Search for Study, Series or Instance DICOM Objects)

- RESTful Services (RS) using HTTP POST: STOW-RS, either:

  1. DICOM Creator (Store Instances)

  2. Metadata and Bulk Data Creator (Store Instances)

- RESTful Services (RS) using HTTP Options: RS Capabilities:

  1. Provided information about the capabilities of a DICOM RESTful web service provider)

### 6.1.1 Media Types

Media types are identifiers used to define the data format of a representation. HTTP uses media types in the Content-Type and Accept header fields in order to provide open and extensible data typing and type negotiation. The syntax of media types is:

        media-type = type "/" subtype *(OWS ";" OWS parameter)

Where

        type = token
        subtype = token
        parameter = token "=" (token / quoted-string) )

The <type>/<subtype> may be followed by parameters in the form of name=value pairs.

The type, subtype, and parameter name tokens are case-insensitive, but the case sensitivity of parameter values depends on the semantics of the parameter name. The presence or absence of a parameter might be significant to the processing of a media-type, depending on its definition within the media type registry.

A parameter value can be transmitted either as a token or quoted-string. The quoted and unquoted values are equivalent.

Media types are defined in [RFC7231] Section 3.1.1.1.

IANA maintains a registry of media types at http://www.iana.org/assignments/media-types/media-types.xhtml.

#### 6.1.1.1 Multipart Media Types

Some of the services defined in this Standard support the multipart media types [RFC2387]. The syntax is:

        multipart-media-type = "multipart" "/" subtype *( OWS ";" OWS parameter )

The "application/multipart-related" media type is used by the RS services. Its syntax is:

        multipart-related = "multipart/related"
                             OWS ";" OWS "type" "=" DQUOTE media-type DQUOTE
                             OWS ";" OWS "boundary" "=" boundary
                             [related-parameters]

Where

        boundary = 0*69bchar bchar-nospace
        bchar = bchar-nospace / SP
        bchar-nospace = DIGIT / ALPHA / "'" / "(" / ") " / "+" / "_" / "," / "-"
                        / "." / "/" / ":" / "=" / "?" "/" / ":" / "=" / "?"
        related-parameters = [";" "start" "=" cid]
                             [";" "start-info" "=" cid-list]
        cid-list = cid cid-list
        cid = token / quoted-string

The "type" parameter is required. It contains the media type of the "root" body part. It always contains the special character "/" and thus requires quote marks.

The <cid> is a content identifier. It should be unique for each part of the multipart message.

Typically, the "start" and "start-info" parameters are not specified, and the "root" is the first body part.

#### 6.1.1.2 DICOM Resource Categories

Table 6.1.1-1 defines Resource Categories that correspond to different SOP Classes. The following sections map each Resource Category to appropriate DICOM and Rendered media types.

Table 6.1.1-1. Resource Categories

Resource Category | Definition
--- | ---
Single Frame Image | This category includes all resources that: are instances of a single frame SOP Class, or are instances of a multi-frame SOP Class that contain only one frame, or are a single frame selected from an instance of a multi-frame SOP Class.
Multi-Frame Image | This category includes all resources that are instances of a multi-frame SOP Class, that are not video and that contain more than one frame.
Video | This category includes all resources that contain more than one frame and: are instances encoded in the MPEG family of transfer syntaxes (which includes MP4 and H265), or are time based (motion) multi-frame images that the origin server is capable of encoding in the MPEG family.
Text | This category includes all resources that: contain the SR Document Content Module (see Section C.17.3 “SR Document Content Module” in PS3.3 ), such as narrative text, structured reports, CAD, measurement reports, and key object selection documents, or contain the Encapsulated Document Module (see Section C.24.2 “Encapsulated Document Module” in PS3.3 ).
Other | This category includes all resources that are not included above.

#### 6.1.1.3 Rendered Media Types

DICOM resources may be converted into non-DICOM media types in order to render them using commonly available non-DICOM software, such as browsers.

For example:

1. A DICOM SOP Instance containing an image could be rendered into the image/jpeg or image/png Rendered Media Types.

2. A DICOM SOP Instance containing a multi-frame image in a lossless transfer syntax could be rendered into a video/mpeg or video/mp4 Rendered Media Type.

3. A DICOM SOP Instance containing a Structured Report could be rendered into a text/html, text/plain, or application/pdf Rendered Media Type.

### Note

Rendered Media Types are usually consumer format media types.

Table 6.1.1-2 specifies the meaning of media type requirements in Table 6.1.1-3.

Table 6.1.1-2. Definition of Media Type Requirement

Requirement | Definition
--- | ---
default | The origin server shall support all default media types.
required | The origin server shall support these media types.
optional | The origin server may support these media types.

Table 6.1.1-3 defines the Rendered Media Types by their Resource Category for the URI, WS, and RS modes.

Table 6.1.1-3. Rendered Media Types by Resource Category

Category | Media Type | URI | WS | RS
--- | --- | --- | --- | ---
Single Frame Image | image/jpeg | default | default | default
image/gif | optional | optional | required
image/png | optional | optional | required
image/jp2 | optional | optional | optional
Multi-Frame Image | image/gif | optional | optional | optional
Video | video/mpeg | optional | optional | optional
video/mp4 | optional | optional | optional
video/H265 | optional | optional | optional
Text | text/html | default | default | default
text/plain | required | required | required
text/xml | optional | optional | required
text/rtf | optional | optional | optional
application/pdf | optional | optional | optional

When an image/jpeg media type is returned, the image shall be encoded using the JPEG baseline lossy 8 bit Huffman encoded non-hierarchical non-sequential process defined in ISO/IEC 10918-1.

### Note

A DICOM encapsulated CDA resource may be returned as a text/xml media type.

The origin server may support additional rendered media types.

#### 6.1.1.4 Acceptable Media Types

The term Acceptable Media Types denotes the media types that are acceptable to the user agent in the response. The Acceptable Media Types are those specified in:

- The <accept> query parameter, which may or may not be present.

- The Accept header field, which shall be present.

- The default media type for the target resource, if any.

All requests that expect a response with a payload, shall include the Accept header field. The response to a request without an Accept header field shall be 406 (Not Acceptable). Even if specific media types are provided in the <accept> query parameter, an Accept header field with one or more values shall be present, at a minimum */*.

The Acceptable Media Types shall be either DICOM media-types or Rendered media types, but not both. If the Acceptable Media Types contains both DICOM and Rendered Media Types, the origin server shall return 409 (Conflict).

The user agent may specify the relative degree of preference for media types, whether in the <accept> query parameter or the Accept header field, using the <weight> parameter. See [RFC7231] Section 5.3.1.

        weight = OWS ";" OWS "q=" qvalue
        qvalue = ("0" ["." 0*3DIGIT]) / ("1" ["." 0*3("0") ])

If no "q" parameter is present, the default qvalue is 1.

#### 6.1.1.5 Accept Query Parameter

The <accept> query parameter is primarily designed for use in hyperlinks (URLs) embedded in documents, where the Accept header field is not accessible. It is similar to the Accept header field, except that it shall not have wildcards (<type>/* or */*).

The <accept> query parameter has the following syntax:

        accept = accept-name "=" 1#(media-type [weight])
        accept-name = "%s" quoted-string

### Note

The "%s" that prefixes the <accept-name> specifies that it is a case sensitive token. See [RFC7405].

Its value is a comma-separated list of one or more <media-type>s, possibly including parameters. It shall be supported by the origin server. It is optional for the user agent.

The <accept-name> of the <accept> query parameter is defined by the Service. It is case-sensitive. Table 6.1.1-4 contains the <accept-name> of the <accept> query parameter for some services.

Table 6.1.1-4. <accept> Query Parameter Name by Service

Service | Name
--- | ---
URI | accept-name = "contentType"
WS | not applicable
RS | accept-name = "accept"

The <accept> query parameter should not be used when the user agent can specify the values in the Accept header field.

All media types present in an <accept> query parameter shall be compatible with a media range in the Accept header field, either explicitly or implicitly through wildcards.

### Note

For example, the presence of image/jpeg in the <accept> query parameter will require the Accept header field to include one of the following values: image/jpeg, image/*, or */*.

#### 6.1.1.6 Accept Header field

The Accept header field is used to specify media ranges acceptable to the user agent. It has the following syntax:

        Accept = 1#(media-range [weight])

Where,

        media-range = media-type
                      / type "/" "*" parameters
                      / "*/*" parameters
        parameters ; See Section 6.1.1

The Accept header field shall be present. Its value shall be a comma-separated list of one or more media ranges acceptable in the response. See [RFC7231] Section 5.3.2.

A media range is either a media-type or a wildcard. Wildcards use the asterisk ("*") to group media types into ranges, with <type>/* indicating all subtypes of that type, and */* indicating all media types from the target's Resource's Category.

For example, the media range "image/*" matches "image/jpeg", which is the default media type for the Single Frame Image Resource Category, and "text/*" matches "text/html", which is the default media type for the Text Resource Category. The "*/*" media range matches the default media type for the target's Resource Category.

If the origin server receives a request without an Accept header field, but that might have a response payload, it shall return a 406 (Not Acceptable).

#### 6.1.1.7 Selected Media Type

The Selected Media Type is the media type selected by the origin server for the response payload. The media types in the <accept> query parameter and the media ranges in the Accept header field shall each be separately prioritized according to the rules defined in [RFC7231] Section 5.3.1.

The Selected Media Type is chosen as follows:

1. Select the target's Resource Category

2. Select the representation with the highest priority supported media type for that category in the <accept> query parameter, which is compatible with the Accept header field.

3. If no media type in the <accept> query parameter is supported, select the highest priority supported media type for that category in the Accept header field, if any.

4. Otherwise, select the default media type for the category if the Accept header field contains a wildcard media range matching the category, if any.

5. Otherwise, return a 406 (Not Acceptable).

For a set of media types in the <accept> query parameter (step 2 above), or for a set of media ranges in the Accept header field (step 3 above), the highest priority supported media type is determined as follows:

1. Assign a <qvalue> of 1 to any member of the set that does not have a one.

2. Assign each representation supported by the origin server the <qvalue> of the most specific media type that it matches.

3. Select the representation with the highest <qvalue>. If there is a tie, the origin server shall determine which is returned.

For example, consider an origin server that receives a request with the following Accept header field:

        Accept: text/*; q=0.5, text/html; q=0.4, text/html; level=1, text/html; level=2; q=0.7, image/png, */*; q=0.4

Suppose that for the resource indicated in the request, the origin server supports representations for the following media types:

        text/html(regular, level 1 and level 2)
        text/rtf
        text/plain
        text/x-latex

These media types are assigned the following <qvalue>s, based on the media ranges above:

Media Type | qvalue | Determining Media Range
--- | --- | ---
text/html; level=1 | 1.0 | text/html; level=1
text/html; level=2 | 0.7 | text/html; level=2
text/plain | 0.5 | text/*
text/rtf | 0.5 | text/*
text/html | 0.4 | text/html
text/x-latex | 0.4 | */*

Although "image/png" has been assigned a default <qvalue> of 1.0, it is not among the supported media types for this resource, and thus is not listed.

The selected media type is "text/html; level=1" since it is the supported media type in the Text Category with the highest qvalue.

### 6.1.2 Character Sets

HTTP uses charset names to indicate or negotiate the character encoding of textual content in representations [RFC6365] Section 3.3.

Character sets may be identified using the value in the IANA Preferred MIME Name column in the IANA Character Set Registry http://www.iana.org/assignments/character-sets/character-sets.xhtml.

Character sets may be identified by using the DICOM Defined Terms for the character set. See Section C.12.1.1.2 “Specific Character Set” in PS3.3 , and Section 6.1.2.3 “Encoding of Character Repertoires” in PS3.5 .

The origin server shall support the "UTF-8" charset name for RS Retrieve Rendered, but is not required to support the DICOM Defined Term "ISO_IR 192".

The syntax is:

        charset = token / defined-term / DQUOTE defined-term DQUOTE

Where

token | A case-insensitive charset name from the Preferred MIME Name in the IANA Character Set Registry.
defined-term | See Section C.12.1.1.2 “Specific Character Set” in PS3.3 .

Some DICOM Defined Terms for character sets contain space characters; and shall be enclosed in double quotes in HTTP header fields and percent encoded in URLs.

The Conformance Statement shall document all supported character sets. The Retrieve Capabilities response for all RS Services shall also document all supported character sets.

A request without any <charset> query parameter or Accept-Charset header field implies that the user agent will accept any charset in the response.

Annex D contains a mapping of some Specific Character Set (0008,0005) Defined Terms to IANA charset tokens.

#### 6.1.2.1 Acceptable Character Sets

The term Acceptable Character Sets denotes the character sets that are acceptable to the user agent in the response. The Acceptable Character Sets are those specified in:

- the "charset" media type parameter

- the <character-set> query parameter

- the Accept-Charset header field

- the default character set for the media type, if any

When the acceptable character sets contains a list of one or more Defined Terms they should be ordered as specified in Section C.12.1.1.2 “Specific Character Set” in PS3.3 and Section 6.1.2.3 “Encoding of Character Repertoires” in PS3.5 . This is especially important for ISO 2022 character sets.

#### 6.1.2.2 Character Set Query Parameter

The <character-set> query parameter is primarily designed for use in hyperlinks (URLs) embedded in documents, where the Accept-Charset header field is not accessible.

The <character-set> query parameter has the following syntax:

        character-set = name "=" 1#(charset [weight])

The <character-set> query parameter value is a comma-separated list of one or more <charset>s. It is similar to the Accept-Charset header field, except that it shall not have wildcards. It shall be supported by the origin server. It is optional for the user agent.

All <charset>s present in the <character-set> query parameter may have a corresponding character set in the Accept-Charset header field, either explicitly or implicitly through wildcards.

The <name> of the <character-set> query parameter is defined by the Service. Table 6.1.2-1 contains the names of the <character-set> query parameter for some services.

Table 6.1.2-1. <character-set> Query Parameter Name by Service

Service | Name
--- | ---
URI | name = "charset"
WS | not applicable
RS Studies | name = "charset"

#### 6.1.2.3 Accept-Charset Header Field

The Accept-Charset header field has the following syntax:

        Accept-Charset = 1#(charset [weight]) / ("*" [weight])

The user agent may provide a list of Acceptable Character Sets in the Accept-Charset header field of the request. Its value is a comma-separated list of one or more <charset>s and/or the wildcard value ("*"). It shall be supported by the origin server. It is optional for the user agent.

The values of the Accept-Charset header field values are prioritized by their <weight> parameter.

If no wildcard ("*") is present, then any character sets not explicitly mentioned in the header field are considered "not acceptable" to the client.

A request without an Accept-Charset header field implies that the user agent will accept any charset in response.

If the media type defines a "charset" parameter, it should be included with the media type in the Accept header field, rather than in the Accept-Charset header field.

#### 6.1.2.4 Selected Character Set

The origin server shall determine the Selected Character Set(s) as follows:

1. Select the first supported character set in the "charset" parameter(s) of the Selected Media Type.

2. Otherwise, select the highest priority supported <charset> in the <character-set> query parameter.

3. Otherwise, select the highest priority supported <charset> in the Accept-Charset header field.

4. Otherwise, if the Selected Media Type has a default character set that is supported, select it.

5. Otherwise, select UTF-8.

Rendered representations returned in the response shall have all contained strings returned in the Selected Character Sets.

If the character set in which the target resource is encoded is not the Selected CharacterSet:

- If the origin server supports transcoding all glyphs used in the target resource into the Selected Character Set,it shall transcode the response payload into the Selected Character Set

- Otherwise, the origin server shall return 406 (Not Acceptable).

### Note

This means that some SOP Instances may be convertible and others will not be, even though they have the same Specific Character Set (0008,0005).

All origin servers shall support conversion to the UTF-8 character set for RS Rendered Retrieve.

If the user agent chooses to perform its own conversion rather than have it done by the origin server:

1. The user agent may omit the Accept-Charset header field or send the "*" wildcard

2. The user agent may transcode the character set replacing all unknown characters with a suitable replacement. For example:

   - A question mark ("?"), or other similar character indicating an unknown character.

   - The corresponding Unicode Code Point for the character, represented as "U+xxxx".

   - The four characters "\nnn", where "nnn" is the 3 digit octal representation of each byte (see PS3.5, 6.1.2.3).

Prev |  | Next
5 Symbols and Abbreviated Terms | Home | 6.2 WADO-URI Request

DICOM PS3.18 2016b - Web Services