The base type for requesting paginated content.
data class ResourceSearchRequest<Flags>( val flags: Flags, val query: String, val itemsPerPage: Int?, val next: String?, val consistency: PaginationRequestV2Consistency?, val itemsToSkip: Long?, val sortBy: String?, val sortDirection: SortDirection?, )
Paginated content can be requested with one of the following
consistency guarantees, this greatly changes the
semantics of the call:
||Consistency is preferred but not required. An inconsistent snapshot might be returned.|
||Consistency is required. A request will fail if consistency is no longer guaranteed.|
consistency refers to if collecting all the results via the pagination API are consistent. We consider the
results to be consistent if it contains a complete view at some point in time. In practice this means that the results
must contain all the items, in the correct order and without duplicates.
If you use the
PREFER consistency then you may receive in-complete results that might appear out-of-order and can
contain duplicate items. UCloud will still attempt to serve a snapshot which appears mostly consistent. This is helpful
for user-interfaces which do not strictly depend on consistency but would still prefer something which is mostly
The results might become inconsistent if the client either takes too long, or a service instance goes down while
fetching the results. UCloud attempts to keep each
next token alive for at least one minute before invalidating it.
This does not mean that a client must collect all results within a minute but rather that they must fetch the next page
within a minute of the last page. If this is not feasible and consistency is not required then
PREFER should be used.
📝 NOTE: Services are allowed to ignore extra criteria of the request if the
next token is supplied. This is
needed in order to provide a consistent view of the results. Clients should provide the same criterion as they
paginate through the results.
Requested number of items per page. Supported values: 10, 25, 50, 100, 250.
A token requesting the next page of items
Controls the consistency guarantees provided by the backend
Items to skip ahead