DICOM PS3.18 2024e - Web Services

8 Common Aspects of DICOM Web Services

This section describes details and requirements that are common to all Web Services defined in this Part of the Standard.

A user agent or origin server that implements a Service in this Part of the Standard shall conform to Chapter 8 unless stated otherwise in the specification of that Service and its Transactions.

8.1 Transactions

Each transaction is composed of a request message and a response message, sometimes referred to as a request/response pair. When used in this Part of the Standard the term "request" means "request message", and "response" means "response message", unless clearly stated otherwise. Figure 8.1-1 is an interaction diagram that shows the message flow of a transaction. When it receives the request, the origin server processes it and returns a response.

The request includes a method, the URI of the Target Resource, and Header Fields. It might also include Query Parameters and a payload.

The response includes a status code, a reason phrase, Header Fields, and might also include a payload.

Interaction Diagram for Transactions

Figure 8.1-1. Interaction Diagram for Transactions


8.1.1 Request Message Syntax

This Part of the Standard uses the ABNF defined in Section 5.1 to define the syntax of transactions.

All Web Services API request messages have the following syntax:

method SP target-uri SP version CRLF
*(header-field CRLF)
CRLF
[payload]

Where

method = "CONNECT" / "DELETE" / "GET" / "HEAD" / "OPTIONS" / "POST" / "PUT"

Each transaction defines the method it uses.

SP= %x20

The US-ASCII Space character

target-uri = "/" {/resource} {?parameters*}

Each transaction defines a URI Template for the Target Resource. The template specifies the format of URIs that reference the Target Resource of a request. See Section 8.1.1.2.

version = ("HTTP" / "HTTPS") "/" ("1.1" / "2")

The version of the HTTP protocol; one of "HTTP/1.1", "HTTP/2", "HTTPS/1.1", or "HTTPS/2".

CRLF = %x0D.0A

A US-ASCII carriage return (%x0D) followed by a linefeed (%x0A).

*(header-field CRLF)

Zero or more Header Fields each followed by a CRLF delimiter.

[payload] = *OCTET / multipart-payload

An optional payload containing zero or more 8-bit OCTETs.

Note

The method, SP, version, CRLF, header-field, and payload are all HTTP productions from [RFC7230], and [RFC7231]. The definitions are reproduced here for convenience.

8.1.1.1 Method

The request method is one of the HTTP methods, such as CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT. See [RFC7230] Section 4.

8.1.1.2 Target Resource

The Target Resource of a request is specified by the Target URI contained in the request message. See Section 8.2.

8.1.1.3 Query Parameters

Query parameters are contained in the query component (see [RFC3986]) of the URI. The user agent may use Query Parameters to supply parameters to the request. See Section 8.3.

8.1.1.4 Request Header Fields

Request Header Fields are used to specify metadata for the request. Most requests have one or more Content Negotiation (see Section 8.4.1) Header Fields. If a request has a payload, the request will have the corresponding Content Representation (see Section 8.4.2) and Payload (see Section 8.4.3) Header Fields.

8.1.1.5 Request Payload

The payload of the request is an octet-stream containing the content of the message. See Section 8.6. The presence of a payload in a request is signaled by a Content-Length or Transfer-Encoding Header Field.

8.1.2 Response Message Syntax

The syntax of a response message is:

version SP status-code SP reason-phrase CRLF
*(header-field CRLF)
CRLF
[payload]

Where

status-code = 3DIGIT

A three-digit code specifying the status of the response.

reason-phrase = *(HTAB / SP / VCHAR)

A human readable phrase that corresponds to the status. An implementation may define its own reason phrases. The reason-phrase syntax is slightly modified from that in [RFC7230]; this Part of the Standard does not allow obsolete text (obs-text) in the reason-phrase.

Note

The status-code production is from [RFC7230].

The origin server shall always return a response message.

8.1.2.1 Status Codes

The response message shall always include a valid 3-digit status code. Section 8.5 defines the status codes used by transactions. IANA maintains a registry of HTTP Status codes. See [IANA HTTP Status Code Registry].

8.1.2.2 Response Header Fields

Response Header Fields are used to specify metadata for the response. The response will have the Content Representation (see Section 8.4.2) and Payload (see Section 8.4.3) Header Fields that correspond to the contents of the payload.

8.1.2.3 Response Payload

The payload of the response is an octet-stream containing one or more representations. See Section 8.6.

A transaction typically defines two types of payloads for a response message: a success payload, and a failure payload.

A failure response payload should contain a Status Report describing any failures, warnings, or other useful information.

DICOM PS3.18 2024e - Web Services