DICOM PS3.18 2020e - Web Services

PS3.18

DICOM PS3.18 2020e - Web Services

DICOM Standards Committee

A DICOM® publication


Table of Contents

Notice and Disclaimer
Foreword
1. Scope
2. Normative References
Bibliography
3. Definitions
Glossary
4. Symbols and Abbreviated Terms
5. Conventions
5.1. Message Syntax
5.1.1. Common Syntactic Rules For Data Types
5.1.2. URI Templates
5.1.3. List Rule('#')
5.2. Web Service Section Structure
5.3. Request and Response Header Field Tables
6. Conformance
7. Overview of DICOM Web Services (Informative)
7.1. DICOM Web Service Types
7.1.1. URI Web Service
7.1.2. RESTful Web Services and Resources
7.2. Resources, Representations, and Target URIs
7.2.1. DICOM Restful Resources
7.2.2. Representations
7.2.3. Target URIs
8. Common Aspects of DICOM Web Services
8.1. Transactions
8.1.1. Request Message Syntax
8.1.1.1. Method
8.1.1.2. Target Resource
8.1.1.3. Query Parameters
8.1.1.4. Request Header Fields
8.1.1.5. Request Payload
8.1.2. Response Message Syntax
8.1.2.1. Status Codes
8.1.2.2. Response Header Fields
8.1.2.3. Response Payload
8.2. Target Resources
8.3. Query Parameters
8.3.1. Query Parameter Syntax
8.3.1.1. Query Parameter Syntax
8.3.2. Query Parameter Usage
8.3.3. Content Negotiation Query Parameters
8.3.3.1. Accept Query Parameter
8.3.3.2. Character Set Query Parameter
8.3.4. Search Query Parameters
8.3.4.1. Attribute Matching
8.3.4.1.1. Matching Rules
8.3.4.2. Fuzzy Matching of Person Names
8.3.4.3. Attributes Included in the Response
8.3.4.4. Response Pagination
8.3.4.4.1. Paging Behavior
8.3.5. Rendering Query Parameters
8.3.5.1. Query Parameters For Rendered Resources
8.3.5.1.1. Image Annotation
8.3.5.1.2. Image Quality
8.3.5.1.3. Viewport Scaling
8.3.5.1.4. Windowing
8.3.5.1.5. ICC Profile
8.3.5.2. Query Parameters For Thumbnails
8.4. Header Fields
8.4.1. Content Negotiation Header Fields
8.4.1.1. Accept
8.4.1.1.1. Charset Media Type Parameter
8.4.2. Content Representation Header Fields
8.4.3. Payload Header Fields
8.5. Status Codes
8.6. Payloads
8.6.1. Payload Format
8.6.1.1. Single Part Payload
8.6.1.2. Multipart Payload
8.6.1.2.1. Multipart Payload Syntax
8.6.2. DICOM Representations
8.6.2.1. Web Service Constraints
8.6.3. Status Report
8.7. Media Types
8.7.1. Multipart Media Types
8.7.2. DICOM Resource Categories
8.7.3. DICOM Media Types and Media Types For Bulkdata
8.7.3.1. The application/dicom Media Type
8.7.3.2. DICOM Metadata Media Types
8.7.3.3. DICOM Bulkdata Media Types
8.7.3.3.1. Uncompressed Bulkdata
8.7.3.3.2. Compressed Bulkdata
8.7.3.4. Transfer Syntax
8.7.3.5. DICOM Media Type Syntax
8.7.3.5.1. DICOM Multipart Media Types
8.7.3.5.2. Transfer Syntax Parameter
8.7.3.5.3. Character Set Parameter
8.7.3.6. Transfer Syntax Query Parameter
8.7.3.7. Acceptable Transfer Syntaxes
8.7.4. Rendered Media Types
8.7.5. Acceptable Media Types
8.7.6. Accept Query Parameter
8.7.7. Accept Header Field
8.7.8. Selected Media Type and Transfer Syntax
8.7.8.1. Selected Media Type
8.7.8.2. Selected Transfer Syntax
8.7.9. Content-Type Header Field
8.8. Character Sets
8.8.1. Acceptable Character Sets
8.8.2. Character Set Query Parameter
8.8.3. Character Set Media Type Parameters
8.8.4. Accept-charset Header Field
8.8.5. Selected Character Set
8.9. Retrieve Capabilities Transaction
8.9.1. Request
8.9.1.1. Resource
8.9.1.2. Query Parameters
8.9.1.3. Request Header Fields
8.9.1.4. Request Payload
8.9.2. Behavior
8.9.3. Response
8.9.3.1. Status Codes
8.9.3.1.1. Response Header Fields
8.9.3.2. Response Payload
8.9.4. Media Types
8.10. Notifications
8.10.1. Overview
8.10.2. Conformance
8.10.3. Transaction Overview
8.10.4. Open Notification Connection Transaction
8.10.4.1. Request
8.10.4.1.1. Target Resources
8.10.4.1.2. Query Parameters
8.10.4.1.3. Request Header Fields
8.10.4.1.4. Request Payload
8.10.4.2. Behavior
8.10.4.3. Response
8.10.4.3.1. Status Codes
8.10.4.3.2. Response Header Fields
8.10.4.3.3. Response Payload
8.10.5. Send Event Report Transaction
8.10.5.1. Request
8.10.5.1.1. Request Payload
8.10.5.2. Behavior
8.10.5.3. Response
8.11. Security and Privacy
9. URI Service
9.1. Overview
9.1.1. Resource Descriptions
9.1.2. Common Query Parameters
9.1.2.1. Mandatory Query Parameters
9.1.2.1.1. Request Type
9.1.2.1.2. Study UID
9.1.2.1.3. Series UID
9.1.2.1.4. Instance UID
9.1.2.2. Optional Query Parameters
9.1.2.2.1. Acceptable Media Types
9.1.2.2.2. Acceptable Character Sets
9.1.3. Common Media Types
9.2. Conformance
9.3. Transactions Overview
9.4. Retrieve DICOM Instance Transaction
9.4.1. Request
9.4.1.1. Target Resource
9.4.1.2. Query Parameters
9.4.1.2.1. Anonymize
9.4.1.2.2. Annotation
9.4.1.2.3. Transfer Syntax
9.4.1.3. Request Header Fields
9.4.1.4. Request Payload
9.4.2. Behavior
9.4.2.1. Request Type
9.4.2.2. Study, Series, and Instance UIDs
9.4.2.3. Anonymize
9.4.2.4. Transfer Syntax UID
9.4.3. Response
9.4.3.1. Status Codes
9.4.3.2. Response Header Fields
9.4.3.3. Response Payload
9.5. Retrieve Rendered Instance Transaction
9.5.1. Request
9.5.1.1. Target Resource
9.5.1.2. Query Parameters
9.5.1.2.1. Frame Number
9.5.1.2.2. Image Annotation
9.5.1.2.3. Image Quality
9.5.1.2.4. Viewport
9.5.1.2.4.1. Viewport Rows
9.5.1.2.4.2. Viewport Columns
9.5.1.2.5. Source Image Region
9.5.1.2.6. Windowing
9.5.1.2.6.1. Window Center
9.5.1.2.6.2. Window Width
9.5.1.2.7. Presentation State
9.5.1.2.7.1. Presentation Series UID
9.5.1.2.7.2. Presentation UID
9.5.1.3. Request Header Fields
9.5.1.4. Request Payload
9.5.2. Behavior
9.5.2.1. Frame Number
9.5.2.2. Windowing
9.5.2.3. Presentation State
9.5.2.4. Source Image Region
9.5.2.5. Viewport
9.5.3. Response
9.5.3.1. Status Codes
9.5.3.2. Response Header Fields
9.5.3.3. Response Payload
10. Studies Service and Resources
10.1. Overview
10.1.1. Resource Descriptions
10.1.2. Common Query Parameters
10.1.3. Common Media Types
10.2. Conformance
10.3. Transactions Overview
10.4. Retrieve Transaction
10.4.1. Request
10.4.1.1. Target Resources
10.4.1.1.1. DICOM Resources
10.4.1.1.2. Metadata Resources
10.4.1.1.3. Rendered Resources
10.4.1.1.4. Thumbnail Resources
10.4.1.2. Query Parameters
10.4.1.3. Request Header Fields
10.4.1.4. Request Payload
10.4.2. Behavior
10.4.3. Response
10.4.3.1. Status Codes
10.4.3.2. Response Header Fields
10.4.3.3. Response Payload
10.4.4. Media Types
10.4.5. Conformance Statement
10.5. Store Transaction
10.5.1. Request
10.5.1.1. Target Resources
10.5.1.1.1. DICOM Resources
10.5.1.2. Query Parameters
10.5.1.3. Request Header Fields
10.5.1.4. Request Payload
10.5.2. Behavior
10.5.3. Response
10.5.3.1. Status Codes
10.5.3.2. Response Header Fields
10.5.3.3. Response Payload
10.5.4. Media Types
10.5.5. Conformance Statement
10.6. Search Transaction
10.6.1. Request
10.6.1.1. Target Resources
10.6.1.2. Query Parameters
10.6.1.2.1. Attribute/Value Pair Requirements
10.6.1.2.2. Search Key Types and Requirements
10.6.1.2.3. Required Matching Attributes
10.6.1.3. Request Header Fields
10.6.1.4. Request Payload
10.6.2. Behavior
10.6.3. Response
10.6.3.1. Status Codes
10.6.3.2. Response Header Fields
10.6.3.3. Response Payload
10.6.3.3.1. Study Resource
10.6.3.3.2. Series Resources
10.6.3.3.3. Instance Resources
10.6.4. Media Types
10.6.5. Conformance Statement
11. Worklist Service and Resources
11.1. Overview
11.1.1. Resource Description
11.1.1.1. Workitems
11.1.1.2. Web Services and DIMSE Terminology
11.1.2. Common Query Parameters
11.1.3. Common Media Types
11.2. Conformance
11.3. Transactions Overview
11.4. Create Workitem Transaction
11.4.1. Request
11.4.1.1. Target Resources
11.4.1.2. Query Parameters
11.4.1.3. Request Header Fields
11.4.1.4. Request Payload
11.4.2. Behavior
11.4.3. Response
11.4.3.1. Status Codes
11.4.3.2. Response Header Fields
11.4.3.3. Response Payload
11.5. Retrieve Workitem Transaction
11.5.1. Request
11.5.1.1. Target Resources
11.5.1.2. Query Parameters
11.5.1.3. Request Header Fields
11.5.1.4. Request Payload
11.5.2. Behavior
11.5.3. Response
11.5.3.1. Status Codes
11.5.3.2. Response Header Fields
11.5.3.3. Response Payload
11.6. Update Workitem Transaction
11.6.1. Request
11.6.1.1. Target Resources
11.6.1.2. Query Parameters
11.6.1.3. Request Header Fields
11.6.1.4. Request Payload
11.6.2. Behavior
11.6.3. Response
11.6.3.1. Status Codes
11.6.3.2. Response Header Fields
11.6.3.3. Response Payload
11.7. Change Workitem State
11.7.1. Request
11.7.1.1. Target Resources
11.7.1.2. Query Parameters
11.7.1.3. Request Header Fields
11.7.1.4. Request Payload
11.7.2. Behavior
11.7.3. Response
11.7.3.1. Status Codes
11.7.3.2. Response Header Fields
11.7.3.3. Response Payload
11.8. Request Cancellation
11.8.1. Request
11.8.1.1. Target Resources
11.8.1.2. Query Parameters
11.8.1.3. Request Header Fields
11.8.1.4. Request Payload
11.8.2. Behavior
11.8.3. Response
11.8.3.1. Status Codes
11.8.3.2. Response Header Fields
11.8.3.3. Response Payload
11.9. Search Transaction
11.9.1. Request
11.9.1.1. Target Resources
11.9.1.2. Query Parameters
11.9.1.3. Request Header Fields
11.9.1.4. Request Payload
11.9.2. Behavior
11.9.3. Response
11.9.3.1. Status Codes
11.9.3.2. Response Header Fields
11.9.3.3. Response Payload
11.10. Subscribe Transaction
11.10.1. Request
11.10.1.1. Target Resources
11.10.1.2. Query Parameters
11.10.1.3. Request Header Fields
11.10.1.4. Request Payload
11.10.2. Behavior
11.10.3. Response
11.10.3.1. Status Codes
11.10.3.2. Response Header Fields
11.10.3.3. Response Payload
11.11. Unsubscribe Transaction
11.11.1. Request
11.11.1.1. Target Resources
11.11.1.2. Query Parameters
11.11.1.3. Request Header Fields
11.11.1.4. Request Payload
11.11.2. Behavior
11.11.3. Response
11.11.3.1. Status Codes
11.11.3.2. Response Header Fields
11.11.3.3. Response Payload
11.12. Suspend Global Subscription Transaction
11.12.1. Request
11.12.1.1. Target Resources
11.12.1.2. Query Parameters
11.12.1.3. Request Header Fields
11.12.1.4. Request Payload
11.12.2. Behavior
11.12.3. Response
11.12.3.1. Status Codes
11.12.3.2. Response Header Fields
11.12.3.3. Response Payload
11.13. Workitem Event Reports
12. Non-Patient Instance Service and Resources
12.1. Overview
12.1.1. Resource Descriptions
12.1.2. Common Query Parameters
12.1.3. Common Media Types
12.2. Conformance
12.3. Transactions Overview
12.4. Retrieve Transaction
12.4.1. Request
12.4.1.1. Target Resources
12.4.1.2. Query Parameters
12.4.1.3. Request Header Fields
12.4.1.4. Request Payload
12.4.2. Behavior
12.4.3. Response
12.4.3.1. Status Codes
12.4.3.2. Response Header Fields
12.4.3.3. Response Payload
12.5. Store Transaction
12.5.1. Request
12.5.1.1. Target Resources
12.5.1.2. Query Parameters
12.5.1.3. Request Header Fields
12.5.1.4. Request Payload
12.5.2. Behavior
12.5.3. Response
12.5.3.1. Status Codes
12.5.3.2. Response Header Fields
12.5.3.3. Response Payload
12.6. Search Transaction
12.6.1. Request
12.6.1.1. Target Resources
12.6.1.2. Query Parameters
12.6.1.3. Request Header Fields
12.6.1.4. Request Payload
12.6.2. Behavior
12.6.3. Response
12.6.3.1. Status Codes
12.6.3.2. Response Header Fields
12.6.3.3. Response Payload
A. Collected ABNF
B. Examples (Informative)
B.1. Retrieving a Simple DICOM Image in JPEG
B.2. Retrieving a DICOM SR in HTML
B.3. Retrieving a Region of A DICOM Image
B.4. Retrieving As A DICOM Media Type
C. Retired
D. IANA Character Set Mapping
E. Retired
F. DICOM JSON Model
F.1. Introduction to JavaScript Object Notation (JSON)
F.2. DICOM JSON Model
F.2.1. Multiple Results Structure
F.2.1.1. Examples
F.2.1.1.1. Native DICOM Model
F.2.1.1.2. DICOM JSON Model
F.2.2. DICOM JSON Model Object Structure
F.2.3. DICOM JSON Value Representation
F.2.4. DICOM JSON Value Multiplicity
F.2.5. DICOM JSON Model Null Values
F.2.6. BulkDataURI
F.2.7. InlineBinary
F.3. Transformation with other DICOM Formats
F.3.1. Native DICOM Model XML
F.4. DICOM JSON Model Example
F.5. Retired
G. WADL JSON Representation
G.1. Introduction
G.2. XML Elements
G.2.1. Doc Elements
G.2.2. Unique Elements
G.2.3. Repeatable Elements
H. Capabilities Description
I. Store Instances Response Module
I.1. Response Message Body
I.2. Store Instances Response Attribute Description
I.2.1. Warning Reason
I.2.2. Failure Reason
I.3. Response Message Body Example

List of Figures

8.1-1. Interaction Diagram for Transactions
8.6-1. Mapping between IOD and HTTP message parts

List of Tables

5.1-1. ABNF for Common Syntactic Values
5.2-1. Request Header Fields
5.2-2. Response Header Fields
8.3.1-1. ABNF for Query Parameter
8.3.2-1. Query Parameter Usage
8.3.2-2. Example Query Parameter Table
8.3.4-1. Query Parameter Syntax
8.3.5-1. Retrieve Rendered Query Parameters
8.3.5-2. Thumbnail Query Parameters
8.4.1-1. Content Negotiation Header Fields
8.4.2-1. Content Representation Header Fields
8.4.3-1. Payload Header Fields
8.5-1. Status Code Meaning
8.6.1-1. Multipart Header Fields
8.7.2-1. Resource Categories
8.7.3-1. Definition of Media Type Requirement
8.7.3-2. Transfer Syntax UIDs for application/dicom Media Types
8.7.3-3. Media Types for Metadata
8.7.3-4. Transfer Syntax UIDs for Uncompressed Data in Bulkdata
8.7.3-5. Media Types and Transfer Syntax UIDs for Compressed Data in Bulkdata
8.7.4-1. Rendered Media Types by Resource Category
8.7.8-1. Media Type QValue Example
8.9.1-1. Request Header Fields
8.9.3-1. Status Code Meaning
8.9.3-2. Response Header Fields
8.10.3-1. Notification Sub-System Transactions
8.10.4-1. Request Header Fields
8.10.4-2. Status Code Meaning
8.10.4-3. Response Header Fields
9.1.2-1. Mandatory Query Parameters
9.1.2-2. Optional Query Parameters
9.4.1-1. Optional Query Parameters
9.4.1-2. Request Header Fields
9.4.3-1. Status Code Meaning
9.4.3-2. Response Header Fields
9.5.1-1. Query Parameters
9.5.1-2. Request Header Fields
9.5.3-1. Status Code Meaning
9.5.3-2. Response Header Fields
10.1-1. Resources and Descriptions
10.1.2-1. Common Query Parameters
10.3-1. Studies Service Transactions
10.3-2. Resources by Transaction
10.4.1-1. Retrieve Transaction DICOM Resources
10.4.1-2. Retrieve Transaction Metadata Resources
10.4.1-3. Retrieve Transaction Rendered Resources
10.4.1-4. Retrieve Transaction Thumbnail Resources
10.4.1-5. Query Parameters by Resource
10.4.1-6. Request Header Fields
10.4.3-1. Status Code Meaning
10.4.3-2. Response Header Fields
10.4.3-3. Resource Media Types
10.4.4-1. Default, Required, and Optional Media Types
10.5.1-1. Store Transaction DICOM Resources
10.5.1-2. Request Header Fields
10.5.2-1. Media Type Transformation to Transfer Syntaxes
10.5.3-1. Status Code Meaning
10.5.3-2. Response Header Fields
10.5.4-1. Default, Required, and Optional Media Types
10.6.1-1. Search Transaction Resources
10.6.1-2. Search Resource Descriptions
10.6.1-3. Search Key Types
10.6.1-4. Required IE Levels by Resource
10.6.1-5. Required Matching Attributes
10.6.1-6. Request Header Fields
10.6.3-1. Status Code Meaning
10.6.3-2. Response Header Fields
10.6.3-3. Study Resource Search Response Payload
10.6.3-4. Series Resources Search Response Payload
10.6.3-5. Instance Resources Search Response Payload
10.6.4-1. Default, Required, and Optional Media Types
11.1.1-1. Resources, URI Templates and Descriptions
11.1.1-2. Correspondence between RESTful and DIMSE Terminology
11.1.2-1. Common Query Parameters
11.1.3-1. Default, Required, and Optional Media Types
11.3-1. Worklist Service Methods and Resource Templates
11.4.1-1. Create Transaction Resources
11.4.1-3. Request Header Fields
11.4.3-1. Status Code Meaning
11.4.3-2. Response Header Fields
11.5.1-1. Request Header Fields
11.5.3-1. Status Code Meaning
11.5.3-2. Response Header Fields
11.6.1-1. Request Header Fields
11.6.3-1. Status Code Meaning
11.6.3-2. Response Header Fields
11.7.1-1. Request Header Fields
11.7.3-1. Status Code Meaning
11.7.3-2. Response Header Fields
11.8.1-1. Request Header Fields
11.8.3-1. Status Code Meaning
11.8.3-2. Response Header Fields
11.9.1-1. Request Header Fields
11.9.3-1. Status Code Meaning
11.9.3-2. Response Header Fields
11.10.1-1. Subscribe Transaction Resources
11.10.1-2. uery Parameters by Resource
11.10.3-1. Status Code Meaning
11.10.3-2. Response Header Fields
11.11.1-1. Unsubscribe Transaction Resources
11.11.3-1. Status Code Meaning
11.11.3-2. Response Header Fields
11.12.1-1. Unsubscribe Transaction Resources
11.12.3-1. Status Code Meaning
11.12.3-2. Response Header Fields
12.1.1-1. Resource Categories, URI Templates and Descriptions
12.1.2-1. Common Query Parameters
12.1.3-1. Default, Required, and Optional Media Types
12.2-1. Required and Optional Transactions
12.3-1. NPI Service Transactions
12.3-2. Resources by Transaction
12.4.1-1. Retrieve Transaction Resources
12.4.1-2. Request Header Fields
12.4.3-1. Status Code Meaning
12.4.3-2. Response Header Fields
12.5.1-1. Store Transaction Resources
12.5.1-2. Request Header Fields
12.5.3-1. Status Code Meaning
12.5.3-2. Response Header Fields
12.6.1-1. Search Transaction Resources
12.6.1-2. NPI Resource Search Attributes
12.6.1-3. Request Header Fields
12.6.3-1. Status Code Meaning
12.6.3-2. Response Header Fields
D-1. IANA Character Set Mapping
F.2.3-1. DICOM VR to JSON Data Type Mapping
F.3.1-1. XML to JSON Mapping
H-1. Resources and Methods
I.1-1. Store Instances Response Module Attributes
I.2-1. Store Instances Response Warning Reason Values
I.2-2. Store Instances Response Failure Reason Values
DICOM PS3.18 2020e - Web Services