6.7 QIDO-RS Request/Response

6.7 QIDO-RS Request/Response (Current)
Prev	6 DICOM Communication Model for Web Services	Next

DICOM QIDO-RS defines several action types. An implementation shall support the following action types:

SearchForStudies

This action searches for DICOM Studies that match specified search parameters and returns a list of matching studies and the requested attributes for each study.
SearchForSeries

This action searches for DICOM Series that match specified search parameters and returns a list of matching series and the requested attributes for each series.
SearchForInstances

This action searches for DICOM Instances that match specified search parameters and returns a list of matching instances and the requested attributes for each instance.

6.7.1 QIDO-RS - Search

6.7.1.1 Request

The specific resources to be used for the search actions shall be as follows:

Resource
- SearchForStudies
  - {+SERVICE}/studies{?query*,fuzzymatching,limit,offset}
- SearchForSeries
  - {+SERVICE}/studies/{StudyInstanceUID}/series{?query*,fuzzymatching,limit,offset}
  - {+SERVICE}/series{?query*,fuzzymatching,limit,offset}
- SearchForInstances
  - {+SERVICE}/studies/{StudyInstanceUID}/series/{SeriesInstanceUID}/instances{?query*,fuzzymatching,limit,offset}
  - {+SERVICE}/studies/{StudyInstanceUID}/instances{?query*,fuzzymatching,limit,offset}
  - {+SERVICE}/instances{?query*,fuzzymatching,limit,offset}
where
- {+SERVICE} is the base URL for the QIDO RESTful service. This may be a combination of protocol (http or https), authority, and path.
- {StudyInstanceUID} is the unique Study Instance UID for a single study.
- {SeriesInstanceUID} is the unique Series Instance UID for a single series.
Method
- GET
Headers
- Accept - The Media Type of the query results. The types allowed for this request header are:
  - multipart/related; type="application/dicom+xml"
    
    Specifies that the results should be DICOM PS3.19 XML (one part per result)
  - application/dicom+json (default)
    
    Specifies that the results should be DICOM JSON as defined in Annex F (the one and only part contains all results)
  A QIDO-RS provider shall support both Accept header values
- Cache-control: no-cache (recommended)
  
  If included, specifies that search results returned should be current and not cached.
{query}
- {attributeID}={value}
  
  0-n / {attributeID}={value} pairs allowed
- includefield={attributeID} | all
  
  0-n includefield / {attributeID} pairs allowed, where "all" indicates that all available attributes should be included for each response.
Each {attributeID} must refer to one of:
- Patient IE attributes
- Study IE attributes
- Series IE attributes (SearchForSeries or SearchForInstances requests only)
- Composite Instance IE attributes (SearchForInstances requests only)
- Additional Query/Retrieve Attributes (Section C.3.4 in PS3.4 )
- Timezone Offset From UTC (0008,0201)
See Section 6.7.1.1.1 for {attributeID} and {value} encoding rules
fuzzymatching=true | false
limit={limit}

The “limit” parameter value is an unsigned integer, which specifies the maximum number of results the origin server shall return. If the “limit” parameter is not present the origin server shall return the maximum number of results in a single response that it supports.
offset={offset}

The “offset” parameter value is an unsigned integer, which specifies the number of results the origin server shall skip before the first returned result. If the “offset” query parameter is not present, its value is 0.

See Section 6.1.4.

6.7.1.1.1 {attributeID} encoding rules

Each {attributeID} query key shall be unique unless the associated DICOM Attribute allows UID List matching (see Section C.2.2.2.2 in PS3.4 ), in which case each {value} will be interpreted to be an element of the UID List.

The acceptable values for {value} are determined by the types of matching allowed by C-FIND for its associated {attributeID} (see Section C.2.2.2 in PS3.4 ). All characters in {value} that are disallowed for URIs shall be percent-encoded. See [RFC3986] for details.

If an {attributeID} is passed as the value of an "includefield" query key this is equivalent to C-FIND Universal matching for the specified attribute (see Section C.2.2.2.3 in PS3.4 ).

{attributeID} can be one of the following:

{dicomTag}
{dicomKeyword}
{dicomTag}.{attributeID}, where {attributeID} is an element of the sequence specified by {dicomTag}
{dicomKeyword}.{attributeID}, where {attributeID} is an element of the sequence specified by {dicomKeyword}

{dicomTag} is the eight character hexadecimal string corresponding to the Tag of a DICOM Attribute (see Chapter 6 in PS3.6 ).

{dicomKeyword} is the Keyword of a DICOM Attribute (see Chapter 6 in PS3.6 ).

Note

Examples of valid values for {attributeID}:

0020000D
StudyInstanceUID
00101002.00100020
OtherPatientIDsSequence.PatientID
00101002.00100024.00400032
OtherPatientIDsSequence.IssuerOfPatientIDQualifiersSequence.UniversalEntityID

Note

Examples of valid QIDO-RS URLs:

http://dicomrs/studies?PatientID=11235813
http://dicomrs/studies?PatientID=11235813&StudyDate=20130509
http://dicomrs/studies?00100010=SMITH*&00101002.00100020=11235813&limit=25
http://dicomrs/studies?00100010=SMITH*&OtherPatientIDsSequence.00100020=11235813
http://dicomrs/studies?PatientID=11235813&includefield=00081048&includefield=00081049&includefield=00081060
http://dicomrs/studies?PatientID=11235813&StudyDate=20130509-20130510
http://dicomrs/studies?StudyInstanceUID=1.2.392.200036.9116.2.2.2.2162893313.1029997326.94587%2c1.2.392.200036.9116.2.2.2.2162893313.1029997326.94583

6.7.1.2 Response

The origin server shall perform the query indicated in the request.

The search requests shall be idempotent, that is, two separate search requests with the same target resource, query parameters, and header fields shall return the same ordered list of results, if the set of matching results on the origin server has not changed.

The results returned in the response are determined as follows:

matches

is the number of matches resulting from the search.

maxResults

is the maximum number of results the origin server allows in a single response.

offset

is the value of the "offset" query parameter. It is the index of the first element in results.

limit

the value of the "limit" query parameter.

results

is the number of returned results. It is equal to the minimum of:

matches – offset, where if the result is less than zero, the result is zero
maxResults
limit

remaining

is the number of remaining matches. It is equal to: matches – (offset + results).

The response is determined as follows:

If (results=0) then there were no matches, and a 204 (No Content) response shall be returned with an empty payload.
Otherwise, a 200 (OK) response shall be returned with a payload containing results
If (remaining > 0) the response shall include a Warning header field (see [RFC7234] Section 5.5) containing the following:

Warning: 299 {+service}: There are <remaining> additional results that can be requested

If the set of matching results has changed due to changes in the origin server contents, then the ordered list of results may be different for subsequent transactions with identical requests, and the results of using the "limit" and "offset" parameters may be inconsistent

The response will be in an Acceptable Media Type.

6.7.1.2.1 Matching

The matching semantics for each attribute are determined by the types of matching allowed by C-FIND (see Section C.2.2.2 in PS3.4 ).

Matching results shall be generated according to the Hierarchical Search Method described in Section C.4.1.3.1.1 in PS3.4 .

Combined Datetime matching shall be performed (see Section C.2.2.2.5 in PS3.4 ).

Note

If a QIDO-RS provider is acting as a proxy for a C-FIND SCP that does not support combined Datetime matching the QIDO-RS provider will need to perform a C-FIND request using Date only and filter results outside the time range before returning a QIDO-RS response

If the TimezoneOffsetFromUTC / 00080201 query key is included in the request, dates and times in the request are to be interpreted in the specified time zone.

If the "fuzzymatching=true" query key/value is included in the request and it is supported then additional fuzzy semantic matching of person names shall be performed in the manner specified in the DICOM Conformance Statement for the service provider.

If the "fuzzymatching=true" query key/value is included in the request and it is not supported, the response shall include the following HTTP Warning header (see [RFC7234] Section 5.5):

Warning: 299 {SERVICE}: "The fuzzymatching parameter is not supported. Only literal matching has been performed."

where {SERVICE} is the base URL for the QIDO-RS provider. This may be a combination of scheme (http or https), host, port, and application.

Note

The Warning header is separate from the Status Line and does not affect the returned Status Code.

6.7.1.2.1.1 Study Matching

Providers of the SearchForStudies service shall support the search query keys described in Table 6.7.1-1:

Table 6.7.1-1. QIDO-RS STUDY Search Query Keys

Key Word	Tag
StudyDate	00080020
StudyTime	00080030
AccessionNumber	00080050
ModalitiesInStudy	00080061
ReferringPhysicianName	00080090
PatientName	00100010
PatientID	00100020
StudyInstanceUID	0020000D
StudyID	00200010

6.7.1.2.1.2 Series Matching

Providers of the SearchForSeries service shall support the search query keys described in Table 6.7.1-1a:

Table 6.7.1-1a. QIDO-RS SERIES Search Query Keys

Key Word	Tag
Modality	00080060
SeriesInstanceUID	0020000E
SeriesNumber	00200011
PerformedProcedureStepStartDate	00400244
PerformedProcedureStepStartTime	00400245
RequestAttributeSequence	00400275
>ScheduledProcedureStepID	00400009
>RequestedProcedureID	00401001

If {StudyInstanceUID} is not specified in the URL and this form of Relational Query is supported, all Study-level attributes specified in Table 6.7.1-1 shall also be supported.

6.7.1.2.1.3 Instance Matching

Providers of the SearchForInstances service shall support the search query keys described in Table 6.7.1-1b:

Table 6.7.1-1b. QIDO-RS INSTANCE Search Query Keys

Key Word	Tag
SOPClassUID	00080016
SOPInstanceUID	00080018
InstanceNumber	00200013

If {StudyInstanceUID} is not specified in the URL and this form of Relational Query is supported, all Study-level attributes specified in Table 6.7.1-1 shall also be supported.

If {SeriesInstanceUID} is not specified in the URL and this form of Relational Query is supported, all Series-level attributes specified in Table 6.7.1-1a shall also be supported.

6.7.1.2.2 Query Result Attributes

6.7.1.2.2.1 Study Result Attributes

For each matching Study, the QIDO-RS provider shall return all attributes in accordance with Table 6.7.1-2:

Table 6.7.1-2. QIDO-RS STUDY Returned Attributes

Attribute Name	Tag	Notes
Specific Character Set	(0008,0005)	If necessary for encoding any returned attributes
Study Date	(0008,0020)
Study Time	(0008,0030)
Accession Number	(0008,0050)
Instance Availability	(0008,0056)
Modalities in Study	(0008,0061)
Referring Physician's Name	(0008,0090)
Timezone Offset From UTC	(0008,0201)	May be absent if no value is available
Retrieve URL	(0008,1190)	Shall be empty if the resource cannot be retrieved via WADO-RS Note The VR of this attribute has changed from UT to UR.
Patient's Name	(0010,0010)
Patient ID	(0010,0020)
Patient's Birth Date	(0010,0030)
Patient's Sex	(0010,0040)
Study Instance UID	(0020,000D)
Study ID	(0020,0010)
Number of Study Related Series	(0020,1206)
Number of Study Related Instances	(0020,1208)
All other Study Level DICOM Attributes passed as {attributeID} query keys that are supported by the service provider as matching or return attributes
All other Study Level DICOM Attributes passed as "includefield" query values that are supported by the service provider as return attributes
All available Study Level DICOM Attributes if the "includefield" query key is included with a value of "all"

Series Level and Instance Level attributes passed as "includefield" query values shall not be returned.

Note

The above list is consistent with those required for IHE RAD-14 (see http://www.ihe.net/uploadedFiles/Documents/Radiology/IHE_RAD_TF_Vol2.pdf Table 4.14-1).

6.7.1.2.2.2 Series Result Attributes

For each matching Series, the QIDO-RS provider shall return all attributes listed in Table 6.7.1-2a:

Table 6.7.1-2a. QIDO-RS SERIES Returned Attributes

Attribute Name	Tag	Notes
Specific Character Set	(0008,0005)	If necessary for encoding any returned attributes
Modality	(0008,0060)
Timezone Offset From UTC	(0008,0201)	May be absent if no value is available
Series Description	(0008,103E)	May be absent if no value is available
Retrieve URL	(0008,1190)	Shall be empty if the resource cannot be retrieved via WADO-RS Note The VR of this attribute has changed from UT to UR.
Series Instance UID	(0020,000E)
Series Number	(0020,0011)
Number of Series Related Instances	(0020,1209)
Performed Procedure Step Start Date	(0040,0244)	May be absent if no value is available
Performed Procedure Step Start Time	(0040,0245)	May be absent if no value is available
Request Attribute Sequence	(0040,0275)	May be absent if no value is available
>Scheduled Procedure Step ID	(0040,0009)
>Requested Procedure ID	(0040,1001)
All other Series Level DICOM Attributes passed as {attributeID} query keys that are supported by the service provider as matching or return attributes
All other Study or Series Level DICOM Attributes passed as "includefield" query values that are supported by the service provider as return attributes
All available Series Level DICOM Attributes if the "includefield" query key is included with a value of "all"
If {StudyInstanceUID} is not specified, all Study-level attributes specified in Table 6.7.1-2

Instance Level attributes passed as "includefield" query values shall not be returned.

Note

The above list is consistent with the attributes required for IHE RAD-14 (see http://www.ihe.net/uploadedFiles/Documents/Radiology/IHE_RAD_TF_Vol2.pdf Table 4.14-1).

6.7.1.2.2.3 Instance Result Attributes

For each matching instance, the QIDO-RS provider shall return all attributes listed in Table 6.7.1-2b:

Table 6.7.1-2b. QIDO-RS Instance Returned Attributes

Attribute Name	Tag	Notes
Specific Character Set	(0008,0005)	If necessary for encoding any returned attributes
SOP Class UID	(0008,0016)
SOP Instance UID	(0008,0018)
Instance Availability	(0008,0056)
Timezone Offset From UTC	(0008,0201)	May be absent if no value is available
Retrieve URL	(0008,1190)	Shall be empty if the resource cannot be retrieved via WADO-RS Note The VR of this attribute has changed from UT to UR.
Instance Number	(0020,0013)
Rows	(0028,0010)	Only present for Image Instances
Columns	(0028,0011)	Only present for Image Instances
Bits Allocated	(0028,0100)	Only present for Image Instances
Number of Frames	(0028,0008)	Only present for Multi-frame image instances
All other Instance Level DICOM Attributes passed as {attributeID} query keys that are supported by the service provider as matching or return attributes
All other Study, Series or Instance Level DICOM Attributes passed as "includefield" query values that are supported by the service provider as return attributes
All available Instance Level DICOM Attributes if the "includefield" query key is included with a value of "all"
If {StudyInstanceUID} is not specified, all Study-level attributes specified in Table 6.7.1-2
If {SeriesInstanceUID} is not specified, all Series-level attributes specified in Table 6.7.1-2a

Note

The above list is consistent with the attributes required for IHE RAD-14 (see http://www.ihe.net/uploadedFiles/Documents/Radiology/IHE_RAD_TF_Vol2.pdf Table 4.14-1 and Table 4.14-2).

6.7.1.2.3 Query Result Messages

The server shall support returning query results as:

XML Results
JSON Results

The result format used shall depend on the Accept header of the request.

6.7.1.2.3.1 XML Results

Content-Type: multipart/related; type="application/dicom+xml"
- The response is a multipart message body where each part is a DICOM PS3.19 XML NativeDicomModel element containing the attributes for one matching Study, Series or Instance (see Section A.1 in PS3.19 ).
- The provider of the QIDO service may use a BulkData reference at its discretion (see Table A.1.5-2 in PS3.19 and Section 6.5.6). For example, this might be done to avoid encoding a large DICOM Value Field, such as an image thumbnail.
- If there are no matching results, the message body will be empty.
Each part in the multipart response will contain the following HTTP headers:
- Content-Type: application/dicom+xml

6.7.1.2.3.2 JSON Results

Content-Type: application/dicom+json
- The response is a DICOM JSON message containing a DICOM JSON property for each matching study, series or instance containing sub-properties describing the matching attributes for each study, series or instance (see Section F.2).
- The provider of the QIDO service may use a BulkDataURI reference at its discretion (see Section F.2.6). For example, this might be done to avoid encoding a large DICOM Value Field, such as an image thumbnail.
- If there are no matching results, the JSON message is empty.

6.7.1.3 Status Codes

Table 6.7-1 lists the HTTP status codes that shall be used to report any of the associated error and warning situations. Other error codes may be present for other error and warning situations.

Table 6.7-1. QIDO-RS HTTP Status Codes

Code	Name	Description
Success
200	OK	The query completed and any matching results are returned in the message body.
Failure
400	Bad Request	The QIDO-RS Provider was unable to perform the query because the Service Provider cannot understand the query component.
401	Unauthorized	The QIDO-RS Provider refused to perform the query because the client is not authenticated.
403	Forbidden	The QIDO-RS Provider understood the request, but is refusing to perform the query (e.g., an authenticated user with insufficient privileges).
413	Request entity too large	The query was too broad and a narrower query or paging should be requested. The use of this status code should be documented in the conformance statement.
503	Busy	Service is unavailable.

Prev	Up	Next
6.6 STOW-RS Request/Response	Home	6.8 RS Capabilities Service