DICOM PS3.18 2021e - Web Services

8.3.4.4 Response Pagination

The following two parameters can be used to paginate a search response that might contain more matches than can readily be handled.

offset = "offset" "=" uint

A single parameter specifies the number of matches the origin server shall skip before the first returned match. The "offset" parameter value is an unsigned integer (uint). If this Query Parameter is not present, its value defaults to 0.

limit = "limit" "=" uint

A single parameter specifies the maximum number of matches the origin server shall return in a single response. The "limit" parameter value is an unsigned integer. If this parameter is not present, its value is determined by the origin server.

8.3.4.4.1 Paging Behavior

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 matches, if the set of matches on the origin server has not changed.

Given the following definitions:

offset

the value of the "offset" query parameter.

limit

the value of the "limit" query parameter.

maxResults

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

matches

the number of matches resulting from the search.

results

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

  • The maximum of zero and the value of matches - offset

  • The value of maxResults

  • The value of limit

remaining

the number of matches that were not yet returned.

The results returned in the response are determined as follows:

  • If (results <= 0) then there are 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 the 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

The response may include a payload containing an appropriate Status Report.

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 "offset" and "limit" parameters may be inconsistent.

DICOM PS3.18 2021e - Web Services