PS-2020a / part18
.pdf
DICOM PS3.18 2020a - Web Services |
Page 151 |
12.3 Transactions Overview
The NPI Service consists of the transactions listed in Table 12.3-1.
Table 12.3-1. NPI Service Transactions
Transaction Method |
Resource |
|
Payload |
|
Description |
||
|
|
|
Request |
Success Response |
|
|
|
Retrieve |
OPTIONS/ |
N/A |
CapabilitiesDescriptionRetrievesadescriptionofthecapabilitiesofthe |
||||
Capabilities |
|
|
|
|
NPIService,includingtransactions,resources, |
||
|
|
|
|
|
query parameters, etc. |
|
|
Retrieve |
GET |
/{npi-name}/{uid}N/A |
Instance and/or StatusRetrieves an Instance, specified by the Target |
||||
|
|
|
|
Report |
ResourceinanAcceptableDICOMMediaType. |
||
Store |
POST |
/{npi-name}{/uid}Instance(s)Status Report |
StoresoneormoreDICOMInstancescontained |
||||
|
|
|
|
|
in the request payload, in the location |
||
|
|
|
|
|
referenced by the Target URL. |
||
Search |
GET |
/{npi-name} |
N/A |
Result(s) and/or StatusSearches the Target Resource for Instances |
|||
|
|
?{params*} |
|
Report |
that match the search parameters and returns |
||
|
|
|
|
a list of matches in an Acceptable DICOM |
|||
|
|
|
|
|
Media Type. |
|
|
The npi-name specifies the type of resource(s) contained in the payload. |
|
|
|
||||
Table 12.3-2 summarizes the Target Resources permitted for each transaction. |
|
|
|
||||
|
|
Table 12.3-2. Resources by Transaction |
|
|
|||
Resource |
|
URI |
Retrieve |
Store |
Search |
Capabilities |
|
NPI Service |
|
/ |
|
|
|
|
X |
All Instances |
|
/{npi-name} |
|
X |
X |
|
|
Instance |
|
/{npi-name}/{uid} |
X |
X |
|
|
|
12.4 Retrieve Transaction
The Retrieve transaction retrieves the target NPI resource in a DICOM Media Type.
12.4.1 Request
The request shall have the following syntax:
GET SP /{npi-name}/{uid} SP version CRLF Accept: 1#dicom-media-type CRLF *(header-field CRLF)
CRLF
12.4.1.1 Target Resources
The target URI shall reference one of the resources shown in Table 12.4.1-1.
An origin server shall specify all supported npi-names in its Conformance Statement and in its response to the Retrieve Capabilities transaction.
- Standard -
Page 152 DICOM PS3.18 2020a - Web Services
|
Table 12.4.1-1. Retrieve Transaction Resources |
Resource |
URI Template |
Instance |
/{npi-name}/{uid} |
|
12.4.1.2 Query Parameters
The user agent shall supply, and the origin server shall support, the Common Query Parameters in Section 12.1.2.
12.4.1.3 Request Header Fields
Table 12.4.1-2. Request Header Fields
Name |
Values |
|
Usage |
Description |
|
|
User Agent |
Origin Server |
|
Accept |
1#-dicom-media-type |
M |
M |
The Acceptable Media Types of the |
|
|
|
|
response payload |
See also Section 8.4.
12.4.1.4 Request Payload
The request shall have no payload.
12.4.2 Behavior
TheoriginservershalltrytolocatetheTargetResourceandiffound,returnitinanAcceptableDICOMMediaType.SeeSection8.7.5. A failure response payload may contain a Status Report describing any failures, warnings, or other useful information.
12.4.3 Response
The response has the following syntax: version SP status-code SP reason-phrase CRLF [Content-Type: dicom-media-type CRLF]
[(Content-Length: uint / Content-Encoding: encoding) CRLF] [Content-Location: url CRLF]
*(header-field CRLF CRLF
[payload / status-report]
12.4.3.1 Status Codes
Table 12.4.3-1 shows some common status codes corresponding to this transaction. See also Section 8.5 for additional status codes.
|
|
|
Table 12.4.3-1. Status Code Meaning |
Status |
|
Code |
Meaning |
Success |
200 |
(OK) |
The instance was successfully retrieved. |
Failure |
400 |
(Bad Request) |
There was a problem with the request. |
- Standard -
|
DICOM PS3.18 2020a - Web Services |
Page 153 |
||
Status |
Code |
|
Meaning |
|
404 (Not Found) |
The origin server did not find a current representation for the Target |
|||
|
|
Resource or is not willing to disclose that one exists. For example, an |
||
|
|
unsupported IOD, or Instance not on server. |
|
|
406 (Unsupported |
The origin server does not support any of the Acceptable Media Types. |
|||
Media Type) |
|
|
|
|
12.4.3.2 Response Header Fields |
|
|
|
|
|
Table 12.4.3-2. Response Header Fields |
|
||
Header Field |
Value |
Origin Server |
Requirements |
|
|
|
Usage |
|
|
Content-Type |
dicom-media-type |
M |
The media-type of the response payload. |
|
Content-Length |
uint |
C |
Shall be present if no content encoding has been |
|
|
|
|
applied to the payload. |
|
Content-Encoding |
encoding |
C |
Shallbepresentifacontentencodinghasbeenapplied |
|
|
|
|
to the payload. |
|
See also Section 8.4.
12.4.3.3 Response Payload
A success response shall have a payload containing the DICOM instance specified by the Target Resource.
A failure response payload may contain a Status Report describing any failures, warnings, or other useful information.
12.5 Store Transaction
This transaction requests that the origin server store the representations of the NPIs contained in the request payload so that they may be retrieved in the future using the SOP Instance UIDs.
12.5.1 Request
The request shall have the following syntax:
POST SP /{npi-name} {/uid} SP version CRLF
Content-Type: dicom-media-type CRLF
(Content-Length: uint / Content-Encoding: encoding) CRLF
CRLF
payload
12.5.1.1 Target Resources
The Target URI shall reference one of the resources shown in Table 12.5.1-1.
An origin server shall specify all supported npi-names in its Conformance Statement and in its response to the Retrieve Capabilities transaction.
- Standard -
Page 154 DICOM PS3.18 2020a - Web Services
Table 12.5.1-1. Store Transaction Resources
Resource |
URI Template |
Description |
All Instances |
/{npi-name} |
Stores representations of a set of Instances. |
Instance |
/{npi-name} {/uid} |
Stores a representation of a single Instance with a |
|
||
|
|
UID equal to uid. |
12.5.1.2 Query Parameters
The user agent shall supply, and the origin server shall support, the Common Query Parameters in Section 12.1.2.
12.5.1.3 Request Header Fields
Table 12.5.1-2. Request Header Fields
Name |
Values |
Usage |
Description |
|
|
|
User Agent |
Origin Server |
|
Content-Type |
media-type |
M |
M |
The DICOM Media Type of the request payload. |
Content-Length |
uint |
C |
M |
Shall be present if a content encoding has not |
|
|
|
|
been applied to the payload. |
Content-Encoding |
encoding |
C |
M |
Shall be present if a content encoding has been |
|
|
|
|
applied to the payload. |
See also Section 8.4.
12.5.1.4 Request Payload
The request payload shall be present and shall contain one or more representations in the DICOM Media Type specified by the Content-Type header field of the message, or for multipart payloads the Content-Type header field of each part.
12.5.2 Behavior
The origin server stores the representations contained in the request payload so that they may be retrieved later using the Retrieve transaction.
Before storing the representations, the origin server may coerce data elements.
If any element is coerced, the Original Attribute Sequence (0400,0561) (see Section C.12.1 “SOP Common Module” in PS3.3) shall be included in the stored DICOM instances. Both the Original Attribute Sequence and the response shall describe the modifications.
12.5.3 Response
The response shall have the following syntax:
version SP status-code SP reason-phrase CRLF
[Content-Type: media-type CRLF]
[(Content-Length: uint / Content-Encoding: encoding) CRLF]
[Content-Location: url CRLF]
*(header-field CRLF)
CRLF
[Status Report]
- Standard -
DICOM PS3.18 2020a - Web Services |
Page 155 |
12.5.3.1 Status Codes
Table 12.5.3-1 shows some common status codes corresponding to this transaction. See also Section 8.5 for additional status codes.
|
|
Table 12.5.3-1. Status Code Meaning |
Status |
Code |
Meaning |
Success200 (OK) |
The origin server successfully stored or created at least one of the representations contained |
|
|
|
in the request payload and is returning a response payload. |
202 |
(Accepted) |
Theoriginserversuccessfullyvalidatedtherequestmessagebuthasnotyetstoredorcreated |
|
|
the representations in the request payload. The origin server may or may not have validated |
|
|
the payload. |
|
|
The user agent can use a Query or Retrieve transaction later to determine if the request has |
|
|
completed. |
Failure 400 |
(Bad Request) |
The was a problem with the request. For example: |
|
|
•the origin server did not store any of the representations contained in the request payload |
|
|
because of errors in the request message, |
|
|
•the request contained an invalid Query Parameter, |
|
|
•the request referenced an invalid instance. |
404 |
(Not Found) |
Theorigin serverdid not find acurrent representation for theTargetResource or isnot willing |
|
|
to disclose that one exists. For example, an unsupported IOD, or Instance not on server. |
409 |
(Conflict) |
The request could not be completed due to a conflict with the current state of the Target |
|
|
Resource. |
415 |
(Unsupported Media |
The origin server does not support the media type specified in the Content-Type header field |
Type) |
of the request, and none of the representations contained in the request were processed or |
|
|
|
stored. |
12.5.3.2 Response Header Fields |
||
Table 12.5.3-2. Response Header Fields
Header Field |
Value |
Origin Server |
Requirements |
|
|
Usage |
|
Content-Type |
dicom-media-type |
M |
The media type of the response payload. |
Content-Length |
uint |
C |
Shall be present if a content encoding has not been |
|
|
|
applied to the payload |
Content-Encoding |
encoding |
C |
Shallbepresentifacontentencodinghasbeenapplied |
|
|
|
to the payload |
See also Section 8.4.
12.5.3.3 Response Payload
If the origin server failed to store or modified any representations in the request payload, the response payload shall contain a Status Report describing any additions, modifications, or deletions to the stored representations. The Status Report may also describe any warnings or other useful information.
- Standard -
Page 156 |
DICOM PS3.18 2020a - Web Services |
12.6 Search Transaction
The Search transaction searches the collection of NPI Instances contained in the Target Resource. The search criteria are specified inthequeryparameters.EachmatchincludesthedefaultandrequestedAttributesfromthematchingInstance.Asuccessfulresponse returns a list describing the matching Instances.
12.6.1 Request
The request shall have the following syntax:
GET SP /{npi-name} {?parameter*} SP version CRLF
Accept: 1#dicom-media-type CRLF
*(header-field CRLF)
CRLF
12.6.1.1 Target Resources
The Target URI shall reference one of the resources shown in Table 12.6.1-1.
An origin server shall specify all supported npi-names in its Conformance Statement and in its response to the Retrieve Capabilities transaction.
Table 12.6.1-1. Search Transaction Resources
Resource |
URI Template |
Description |
All Instances |
/{npi-name} |
Searches a collection of NPI Instances. |
12.6.1.2 Query Parameters
The user agent shall supply, and the origin server shall support, the Common Query Parameters in Section 12.1.2.
The origin server shall support Query Parameters as required in Table 8.3.4-1.
The user agent shall supply in the request Query Parameters as required in Table 8.3.4-1.
For each Resource Category the origin server supports, it shall support the behaviors and matching key Attributes specified in the corresponding sections in Table 12.6.1-2.
Table 12.6.1-2. NPI Resource Search Attributes
Resource Category |
Behaviors and Matching Key Attributes |
Color Palette |
Section X.6.1.2 “Color Palette Attributes” in PS3.4. |
Defined Procedure Protocol |
Section HH.6.1.2 “Defined Procedure Protocol Attributes” in PS3.4. |
Hanging Protocol |
Section U.6.1.2 “Hanging Protocol Attributes” in PS3.4. |
Implant Template |
Section BB.6.1.2 “Implant Template Attributes” in PS3.4. |
12.6.1.3 Request Header Fields
Table 12.6.1-3. Request Header Fields
Name |
Values |
|
Usage |
Description |
|
|
User Agent |
Origin Server |
|
Accept |
1#-dicom-media-type |
M |
M |
The Acceptable Media Types of the |
|
|
|
|
response payload |
- Standard -
DICOM PS3.18 2020a - Web Services |
Page 157 |
See also Section 8.4.
12.6.1.4 Request Payload
The request has no payload.
12.6.2 Behavior
The origin server shall perform the search indicated by the request, using the matching behavior specified in Section 8.3.4.1.1 and in the corresponding sections in Table 8.3.4-1.
The rules for search results are specified in Section 8.3.4.
12.6.3 Response
The response shall have the following syntax:
version SP status-code SP reason-phrase CRLF
[Content-Type: dicom-media-type CRLF]
[(Content-Length: uint / Content-Encoding: encoding) CRLF]
[Content-Location: url CRLF]
*(header-field CRLF
CRLF
[payload / status-report]
12.6.3.1 Status Codes
Table 12.6.3-1 shows some common status codes corresponding to this transaction. See also Section 8.5 for additional status codes.
|
|
Table 12.6.3-1. Status Code Meaning |
|
Status |
|
Code |
Meaning |
Success |
200 (OK) |
The query completed and any matching results are returned in the message |
|
|
|
|
body. |
Failure |
400 |
(Bad Request) |
Therequestmessagecontainedanerror.Forexample,theQueryParameters |
|
|
|
were invalid |
|
406 |
(Unsupported Media Type) |
The origin server does not support any of the Acceptable Media Types. |
|
413 |
(Payload Too Large) |
The search was too broad, and the body of the response should contain a |
|
|
|
Status Report with additional information about the failure. |
12.6.3.2 Response Header Fields
Table 12.6.3-2. Response Header Fields
Header Field |
Value |
Origin Server |
Requirement |
|
|
Usage |
|
Content-Type |
dicom-media-type |
M |
The media type of the response payload. |
Content-Length |
Uint |
C |
Shall be present if a content encoding has not been |
|
|
|
applied to the payload. |
Content-Encoding |
Encoding |
C |
Shall be present if a content coding has been applied |
|
|
|
to the payload. |
- Standard -
Page 158 |
DICOM PS3.18 2020a - Web Services |
See also Section 8.4.
12.6.3.3 Response Payload
A success response shall contain the search results in an Acceptable Media Type. See Section 8.7.5.
A failure response payload may contain a Status Report describing any failures, warnings, or other useful information.
- Standard -
DICOM PS3.18 2020a - Web Services |
Page 159 |
A Collected ABNF
AmachinereadablecollectedABNFforthesyntaxdefinedinthisPartoftheStandardcanbefoundatftp://medical.nema.org/medical/ dicom/ABNF/part18_abnf.txt
- Standard -
Page 160 |
DICOM PS3.18 2020a - Web Services |
- Standard -