14 November 2014Sup 183 Web Services Re-Documentation (V4)Page 1

14 November 2014Sup 183 Web Services Re-Documentation (v4)Page 1

New Structure of Part 18

Open Issues

• URI or URL

Notice and Disclamer

Forward

1Scope

2Conformance

3Normative References

4Term and Definitions

DICOM Terms

Attribute

Tag

Instance

instanceUID

object

objecID

Series

seriesUID

Study

studyUID

HTTP Terms

Content Coding

An encoding transformation that can be applied to a representation. Content codings areprimarily used to allow a representation to be compressed or otherwise transformed without losing the identity of itsunderlying media type and without loss of information. See [rfc7231, Section 3.1.2.1 >] for details.

Version

Method

Resource

Target Resource

Header Fields

Payload

Status Code

Reason Phrase

Web Terms

URI Terms

Scheme

Authority

Path

Query Component

Query Parameter

Fragment

5Symbols and Abbreviated Terms

6Web Services Overview

READ THIS SECTION FIRST!!!! These requirement apply to all DICOMweb services.

This section is intended to be a preamble for sections 7, 8, and 9..

6.1HTTP/HTTPS Transactions

6.2HTTP fundamentals

Case-Sensitivity

URIs

Defined in and

• URI – for all URIs % encoded triplets are case insensitive and should be normalized to uppercase.
• Scheme and Host are case insensitive and should be normalized to lowercase
• All other part of the URI are defined by HTTP 3280 to be case sensitive

HTTP Header Field Names are case insensitive

All transfer-coding names are case insensitive

Connection options are case insensitive

Conventions we are following

6.3Service Description

Each service defined in this standard is described according to:

1. The components of the request messages;
2. The behavior of the Origin-Server; and
3. The components of the response message.

6.3.1Request Message

GET {

The request message is composed of:

• A required resource,
• zero or more query parameters,
• a set of header fields, and
• a possibly emptypayload.

Note

None of the protocols or services defined in this Part of the[JFP1] Standard use the Fragment Component [ref] of the request URI.

6.3.1.1Resource

DICOMweb uses the URI syntax as defined in [RFC 3986 Uniform Resource Identifier (URI): Generic Syntax< >].

6.3.1.2Query Parameters

DICOMweb uses the Query Component of the URI [RFC 3986< >]to specify parameters, called Query Parameters. Query parameters are used to further specify the meaning of request messages.

DICOMweb extends the URI grammar defined in [RFC 3986< >]by defining the syntax of Query Parameters using [RFC 5234 Augmented BNF for Syntax Specifications: ABNF >].

The syntax of query parameters is defined as follows:

query-component = parameter [ *("&" parameter) ]
parameter = name "="" value
name = 1*(ALPHA) *(ALPHA / DIGIT / "_"[JFP2])
value = *char [ *(“,” *char) ]
char = unreserved / pct-encoded / special

unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"

pct-encoded = "%" HEXDIG HEXDIG
special = "/" / "?" / ":" / "@" / "!" / "$" / "'"
/ "(" / ")" / "*" / "+" / ";"

query-component = parameter [ *("&" parameter) ]
parameter = name "="" value
name = *qchar*(ALPHA / DIGIT / "_"[JFP3])
value = *pchar [ *(“,” *pchar) ]
pchar = unreserved / pct-encoded / special

unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"

pct-encoded = "%" HEXDIG HEXDIG
special = "/" / "?" / ":" / "@" / "!" / "$" / "'"
/ "(" / ")" / "*" / "+" / "," / ";"

Note

1.This grammar allows the query component to contain any legal characters as defined by RFC 3986.

2.No whitespace is permitted in URIs. Whitespace around line breaks and the line breaks themselves should be stripped before parsing the URI (See RFC 3986 Appendix C).

3.If the "?" appears in the URI then there must be a legal query parameter in the URI. [RFC 3986] does not permit an empty query component.

4.The grammar above uses <char> instead of <pchar> to limit the scope of parameter names to legal identifiers in most programming languages.

5.The <unreserved>, and <pct-encoded> rules above are defined in [RFC 3986].

6.3.1.3Header Fields

6.3.1.3.1Content Negotiation

All DICOMweb service requests that expect to receive a response with a payload should provide one or more of the following content negotiation header fields [ref

Accept[JFP4]

The Accept header field is used by User-Agents to specify a list of media types that are acceptable in the response payload. See [RFC7231, Section 5.3.2 < >].

The media types in the Accept header can be given a priority ordering by using [Quality Values

DICOMweb has extended the use of this header field and recommends that all requests use this header field.

Accept-Encoding

The Accept-Encoding header field is used by User-Agents to specify a list of content-codings [RFC7231, Section 3.1.2.1< that are acceptable in the response payload.

Accept-Charset

The Accept-Charset header field is used by User-Agents to specify a list of character set namesthat are acceptable in the response payload with one of the textual media types[JFP5]. See [RFC7231, Section 5.3.3<

Textual media types are identified in Table x.y.z.

Character set names are case-insensitive. The User-Agent shall use IANA Character Set Names if defined in the [IANA Character Setsregistry >].

Appendix XX lists DICOM character sets with links totheir corresponding names in the IANA Character Set registry.

Accept-Language

The Accept-Language header field is used by User-Agentsto specifya list of natural languages that are preferred in the response payload. See [IETF RFC7231, Section 5.3.5

DICOMweb does not define any use of this header field.

6.3.1.3.2Representation Metadata[JFP6]

The header fields described in this section are used to specify the representations contained in the payload of a message. All messages that contain a payload should include the following header fields.

Content-Type

The Content-Type header field is used to specify the media type of the payload. Depending on the media type this header field may not fully specify the contents of the payload. See [RFC7231, Section 3.1.1.5 >].

Content-Location

The Content-Location header field is used to specify a URI that references the specific resource corresponding to the representation in this message's payload. See [RFC7231, Section 3.1.4.2< >].

Content-Length

The Content-Length header field is used to describe the length of the payload.

When the payload does not include the length of the payload, the Content-Length header field is required.

for messages withthat include a payload body, the Content-Length field-valueprovides the framing information necessary for determining where the body (and message) ends. For messages that do not include a payload body, the Content-Length indicates the size of the selectedrepresentation (Section 3 of [RFC7231]).[JFP7]

This header field shall be present when there is a payload that without content codings

The following optional header fields are used to specify information about the payload:

Content-Encoding

TODO

Content-Language

TODO

6.3.1.3.3Header Field Parameters

Quality Values

6.3.1.4Payload

The message body (if any) of an HTTP message is used to carry the payload body or payload of that request or response. The message body is identical to the payload unless a transfer coding has been applied, as described in [RFC 7230, Section 3.3.1< standard uses the termspayload, payload body,and message payload interchangeably to denote the message body before any transfer codinghas been applied to it.

All messages have payloads, but the payload may be empty, i.e. length = zero.

The rules for when a payload is allowed in a message differ for requests and responses.

• The presence of a message body in a request is signaled by aContent-Length or Transfer-Encoding header field.
• The presence of a message body in a response depends on both the request method to which it is responding and the response (status code)< >.

6.3.2Behavior

The Behavior section of the Service describes processing that occurs on the Origin-Server base on the information in the request message, in order to create the information in the response message.

[We need to discuss the semantics of the request, target resource set, and what media types are use, DICOMweb behavior is different from 7231.5.3.2]

The Origin-Server shall return an error if it cannot provide the representation in any acceptable media type. This constrains the behavior defined in [RFC7231, Section 5.3.2< >].

There are no requirements for language negotiation in DICOM.

6.3.3Response Message

The response message is composed of:

• A required status code,
• an optional reason phase,
• a set of header fields, and
• a possibly empty payload.

The following sections explain the contents of these components.

6.3.3.1Status

This part of the service description defines the status codes and associated reason phrases that are available in the response.

6.3.3.2Header Fields

This part of the service descriptions defines the header fields that are required, conditionally required, or optional in the response.

If the response has a payload some or all of the Representation Metadata header fields (see [ref]) should be present.

6.3.3.3Payload

The presence of a payload in a response depends on both the request method to which it is responding and the response (status code)< >.

6.3.4Media Types

Each protocol, and in some cases services, have a section that describes the media types supported by the protocol or service.

7URI Protocol (WADO-URI)

7.1Introduction

[explain why it is called URI and give some history]

Include references

7.2URI Services

The URI Protocol is composed of the following services:

Retrieve DICOM Service

Returns a single DICOM instance by retrieving the resourcein the ‘application/dicom’ media type.

Retrieve Rendered Service

Returns a singleimageby rendering the resourcein an acceptable media type.

Retrieve Rendered Presentation State Service

Returns a single imageby rendering the presentation state specified by the resource in an acceptable media-type.

7.2.1Request

All URI Services have the following request message format.

GET {+service} {?query}HTTP/1.1 CRLF

{headers} CRLF

CRLF

Note

1.Literal characters in the format are in bold face, parameters are specified using URI Templates<ref>, the symbol CRLF stands for the US-ASCII carriage return (0x12) and linefeed (0x13) [JFP8]literal characters.[JFP9]

2.The URI protocol uses the HTTP protocol version 1.1.

All URI Protocol request messages

• use the GET method,
• use the HTTP/1.1 protocol,
• use the standard content negotiation[RFC7230, Section < >] header fields, and
• require the object identification query parameters,
• comply with the following sections.????

7.2.1.1Service

{+service}specifies the address of the service. It is composed of the authority and path components of the URI.

7.2.1.2Query Parameters

7.2.1.2.1Object Identification Parameters

User-Agents shall include all parameters in this section in all URI requests. The Origin-Server shall support all parameters in this section.

7.2.1.2.1.1Request Type

requestType = WADO

The “requestType”specifies that this is a URI (WADO) request. Its value shall be "WADO".

7.2.1.2.2Unique Identifier of the Study

studyUID = { uid }

The “studyUID” parameter identifies the study that contains theobject of this request[JFP10]. Its value shall be a Study Instance UID, as defined in PS3.3 [ref], except that[JFP11] it shall not be padded to an even length with a NULL character.

7.2.1.2.3Unique Identifier of the Series

seriesUID = { uid }

The “seriesUID” parameter identifies the series that contains the object of this request. Its value shall be a Series Instance UID, as defined in PS3.3 [ref].

7.2.1.2.4Unique Identifier of the Instance

objectUID = { uid }

The “objectUID” parameter identifies the instance that contains the object of this request. Its value shall be a SOP Instance UID, as defined in PS3.3 [ref].

7.2.1.3Other Query Parameters

7.2.1.3.1De-Identify

TODO

7.2.1.3.2Media Type of the Response (Retired)

This section was previously defined in DICOM. It is now retired.See PS 3.18-2014b.

Media types are specified using the Accept header field. See[Section < # >].

7.2.1.3.3Transfer Syntax UID (Retired)

This section was previously defined in DICOM. It is now retired.See PS 3.18-2014b.

Transfer syntaxis specified as a media type parameter in the Accept or Content-Type header fields as appropriate. See …

7.2.1.3.4Charset of the Response (Retired)

This section was previously defined in DICOM. It is now retired.See PS 3.18-2014b.

Character set is specified using the Accept-Charset header field. See Section x.y.z< >.

7.2.1.4Header Fields

User-Agents shall support all parameters in this section in all URI requests.

Required:

Accept

[move ]The Accept header field is used to specify a list a media types that are acceptable to the User-Agent in the response payload. It is recommended that the Accept header be used in preference to the “contentType” query parameter (see ref) and that it be included in all request messages. (See ref)

Optional:

Accept-Charset

[move] The Accept-Charset header is used to specify the character sets that are acceptable to the User-Agent in the response payload. It is recommended that the Accept header be used in preference to the “charset” query parameter (see ref) and that it be included in all request messages. (See ref)

7.2.1.5Request Payload

URI Services have an empty request payload.

7.2.2Behavior

The Origen-Server uses the object identification query parameters to specify the instance that is the target of the request. The processing of that instance and the response are specified in the individual URI services define below.

7.2.3Response

7.2.3.1Status Codes

Table 7.2-x specifies status codes that URI servicescan return.

Table 7.2-x Status Codes for URI Services

Status / Reason Phrase / Description
200 / OK / The requested resource is contained in the payload.
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

NoteThe Reason Phrase listed in Table 7.2-x are those suggested in the HTTP standard, but they should not be relied upon. The reason phrase is designed to be human readable and the Origin-Server is free to provide its own reason phrase.

7.2.3.2Header Fields

Recommended:

Content-TypeSee [ref].

Content-LocationSee [ref].

Recommend If:The payload has no transfer codings applied to it.

Content-LengthSee [ref]’.

Optional:

Content-Encoding:See [ref].

Content-Language:See [ref].

7.2.3.3Payload

Each of the URI Services define the media types available in their response payloads.

7.3Retrieve DICOM Service

The Retrieve DICOM Service specifies a single DICOM SOP Instance in the request and receives a single DICOM SOP Instance in PS 3.10 formatin a successful response.

7.3.1Request

The Retrieve DICOM Service request message has the same format as all URI request messages, except for the following differences:

7.3.1.1Resource

Specifies the address of this service.

7.3.1.2Query Parameters

This service supports the object identification query parameters and the anonymize query parameter.

7.3.1.3Header Fields

The value of the Accept header field shall be ‘application/dicom’ media type.

7.3.1.4Payload

The request payload is empty.

7.3.2Behavior

The Origin-Server retrieves the instance specified in the object identification query parameters and returns it in the response.

7.3.3Response

7.3.3.1Status Codes[JFP12]

See section [ref].

7.3.3.2Header Fields

Required:

Content-TypeSee [ref].

Content-LocationSee [ref].

Required If:The response payload has no transfer codings applied to it.

Content-LengthSee [ref].

Optional:

Content-EncodingSee [ref].

Content-LanguageSee [ref].

7.3.3.3Payload

The Retrieve DICOM response payload is a composite DICOM object in the format defined in PS 3.10[ref].

7.3.4Media Types

The Retrieve DICOM service only supports the ‘application/dicom’ media type (see ref).

7.4URI Retrieve Rendered Service

The URI Retrieve Rendered Service retrieves instances in a rendered media type.

7.4.1Request

The URI Retrieve Rendered request message has the same format as all URI request messages, except for the following differences:

1.The referenced object may not be a presentation series on instance object.

3.The service provides additional query parameters that specify how the Origin-Server shouldrender the DICOM object.

7.4.1.1Resource

The resource component of the URI specifies this service.

7.4.1.2Query Parameters

In addition to the object identification query parameters available to all URI services [ref], This service supports additional query parameters that specify how the identified object is rendered.

The following rules pertain to all parameters defined in this section:

1. All parameters in this section are optional.
2. These parameters only apply to image and video media types, as defined in Section X.X, and therefore, shall not be present for any DICOM media types.
3. The data types of the parameter values are defined in Section [ref]
4. Unless otherwise specified the image (or selected region) is sent in its original size.[JFP13][JFP14]

7.4.1.2.1Annotation on the Object[JFP15]

annotation = { patient | technique }

The “annotation” parameter specifies that annotations should be applied to the retrieved image. Its value shall be a non-empty, comma separated list of one or more of the following items:

patient– displays patient information (e.g., patient name, birth date, etc.)

technique– displays technique information (e.g., image number, study date, image position, etc.).

When used in conjunction with the region parameter, it shall be applied after the selection??? of the region.

The exact nature and presentation of the annotation is determined by the Origin-Server.

7.4.1.2.2Number of Pixel Rows

rows = { integer }

The “rows” parameter specifies the height in pixels of the returned image. The returned image shall have the same aspect ratio as the original image.

Note:If both "rows" and "columns" are specified, then the Origin-Server will choose one arbitrarily.

7.4.1.2.3Number of Pixel Columns

columns = { integer }

The “columns” parameter specifies the width in pixels of the returned image. The returned image shall have the same aspect ratio as the original image.

NoteSee note in Number of Pixel Columns above.

7.4.1.2.4Region of the Image

region = { top, left, bottom, right }

The “region” parameter requests a rectangular region of the original image. Its value shall be a list of four comma separated, positive secimal strings, representing in the following order:

topthe top row of the region,

leftthe left column of the region,

bottomthe bottom row of the region,

rightthe right column of the region,

The region is specified using a normalized coordinate system relative to the size of the original image, measured in rows and columns. Where

0.0 corresponds to the top row and left column of the image,

1.0 corresponds to the bottom row and right column of the image, and