8.3.4.4 Response Pagination

8.3.4.4 Response Pagination (Current)
Prev	8.3.4 Search Query Parameters	Next

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 as specified in 8.3.4.4.1.

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. For a Repository Query, this is the value of Maximum Number of Records (0008,0429).
maxResults	the maximum number of results the origin server allows in a single response (i.e., system limit).
matches	the number of matches resulting from the search. If Prior Record Key (0008,041C) is provided in the query, then the value will be the number of matches after the record identified by the attribute value.
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.

Prev	Up	Next
8.3.4.3 Attributes Included in the Response	Home	8.3.4.5 Empty Value Matching