Subject: [scim] Pagination Question

From: Shelley <[email-masked]>
Date: Mon, 18 Nov 2013 16:09:48 -0600

Thanks, Phil.

To clarify, since I posed the "startIndex" as an open-ended question, and
not a proposal, here is my proposal for handling the startIndex attribute
in those scenarios.

When the *requested startIndex is greater than the number of results*, or
there are *no results*, return the *requested startIndex *with *0
itemsPerPage*.

Requested startIndex is greater than totalResults:

*GET /Users?startIndex=20*
{
  "totalResults":19,
  "itemsPerPage":0,
  "startIndex":20,
  "Resources":[]
}

No results:

*GET /Users?count**=10*
{
  "totalResults":0,
  "itemsPerPage":0,
  "startIndex":1,
  "Resources":[]
}

While I agree these are fairly minor points, I believe that these are
ambiguities that should be addressed and clarified in the specification.

---------- Forwarded message ----------
> From: Phil Hunt <[email-masked]>
> To: Shelley <[email-masked]>
> Cc: "[email-masked]" <[email-masked]>
> Date: Fri, 15 Nov 2013 16:20:44 -0800
> Subject: Re: [scim] Pagination Question
> Shelley,
>
> +1 to your questions (both emails).
>
> I don't think most of these matter much.  Just that we pick a particular
> behaviour for interop consistency.
>
> Phil
>
> @independentid
> www.independentid.com
> [email-masked]
>
> On 2013-11-15, at 6:44 AM, Shelley <[email-masked]> wrote:
>
> The SCIM specification defines the *startIndex *for a pagination response
> as a "1-based index of the first result in the current set of search
> results". However, what is an appropriate value for this attribute if
> pagination is requested but *the requested startIndex is greater than the
> total number of results*? Also, what is an appropriate value (if any) if
> there are *no results*?
>
> Further, the specification defines *itemsPerPage *as a "non-negative
> integer" which "specifies the number of search results returned in a query
> response page". If pagination is requested by the consumer, but there are *no
> results*, is it appropriate to return *0* for this value?
>
> For more details and examples regarding these questions, please review the
> previous post [1].
>
> [1] http://www.ietf.org/mail-archive/web/scim/current/msg01361.html
>
>
> On Wed, Nov 6, 2013 at 1:51 PM, Shelley <[email-masked]> wrote:
>
>> I'd appreciate some clarification on some of the SCIM pagination
>> behavior, particularly as it relates to situations when the "startIndex"
>> and/or "count" exceed the total number of results.
>>
>> Given the following example scenarios, assume there are 19 total users,
>> and the SP has configured a default maxResults of 10. (The schemas
>> attribute and actual resources have been omitted for brevity and
>> applicability with both SCIM 1.1 and 2.0.)
>>
>> *Scenario 1*
>> *GET /Users?startIndex=2*
>> {
>>   "totalResults":19,
>>   "itemsPerPage":10,
>>   "startIndex":2,
>>   "Resources":[
>> *    ...users 2-11...*
>>   ]
>> }
>> Is this the correct behavior, such that the "current" page contains the
>> default "itemsPerPage" despite the "previous" page being a different size?
>>
>> *Scenario 2*
>> *GET /Users?startIndex=19&count=10*
>> {
>>   "totalResults":19,
>>   "itemsPerPage":1,
>>   "startIndex":19,
>>   "Resources":[
>> *    ...user 19...*
>>   ]
>> }
>> Despite the requested page size being 10, the actual number of resources
>> returned is only 1. In this situation, is it correct for the SP to return
>> "1" for the "itemsPerPage" or should this value instead be 10?
>>
>> *Scenario 3*
>> *GET /Users?startIndex=20*
>> {
>>   "totalResults":19,
>>   "itemsPerPage":0,
>>   "startIndex":20,
>>   "Resources":[
>> *    ...no users/empty array...*
>>   ]
>> }
>>
>> *-OR- *{
>>   "Errors":[
>>     {
>>       "description":"startIndex exceeded totalResults",
>>       "code":"400"
>>     }
>>   ]
>> }
>> If the requested startIndex is greater than the total number of results,
>> what should the SP return? Is this an error condition? If not, what are the
>> appropriate values for the startIndex and itemsPerPage?
>>
>> Thank you!
>>
>
> _______________________________________________
> scim mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/scim
>
>
>
> _______________________________________________
> scim mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/scim
>
>

---

From: Shelley <[email-masked]>
Date: Wed, 20 Nov 2013 09:09:10 -0600

What is the expected pagination behavior when *count=0*? Should this return *no
results*, or is 0 a special value that may be used to indicate that the *max
results *should be returned?

My assumption would be the former (no results), given that neither SCIM nor
the OpenSearch specification seem to treat "0" as a special value, and the
only restriction on it is that it is a non-negative integer; however, I
have seen some pagination behavior where 0 is treated as a special value
indicating that all results should be returned.

On Mon, Nov 18, 2013 at 4:09 PM, Shelley <[email-masked]> wrote:

>> The SCIM specification defines the *startIndex *for a pagination
>> response as a "1-based index of the first result in the current set of
>> search results". However, what is an appropriate value for this attribute
>> if pagination is requested but *the requested startIndex is greater than
>> the total number of results*? Also, what is an appropriate value (if
>> any) if there are *no results*?
>>
>> For more details and examples regarding these questions, please review
>> the previous post [1].
>>

---

From: Shelley <[email-masked]>
Date: Wed, 20 Nov 2013 14:34:30 -0600

Also, what is the expected behavior when *startIndex=0*? The spec only
indicates that this must be "non-negative", yet since it is 1-based, what
would a value of 0 represent?

I would propose this should be considered invalid, and returned as an
error, and the spec should be modified to indicate that this parameter must
be a "*positive *integer" rather than a "non-negative integer" in order to
better exclude 0 as a potential value.

On Wed, Nov 20, 2013 at 9:09 AM, Shelley <[email-masked]> wrote:

> What is the expected pagination behavior when *count=0*? Should this
> return *no results*, or is 0 a special value that may be used to indicate
> that the *max results *should be returned?
>
> My assumption would be the former (no results), given that neither SCIM
> nor the OpenSearch specification seem to treat "0" as a special value, and
> the only restriction on it is that it is a non-negative integer; however, I
>> When the *requested startIndex is greater than the number of results*,
>> or there are *no results*, return the *requested startIndex *with *0
>> itemsPerPage*.
>>
>>> if pagination is requested but *the requested startIndex is greater
>>> than the total number of results*? Also, what is an appropriate value
>>> (if any) if there are *no results*?
>>>
>>>> Despite the requested page size being 10, the actual number of
>>>> resources returned is only 1. In this situation, is it correct for the SP
>>>> to return "1" for the "itemsPerPage" or should this value instead be 10?
>>>>
>>>> *Scenario 3*
>>>> If the requested startIndex is greater than the total number of
>>>> results, what should the SP return? Is this an error condition? If not,
>>>> what are the appropriate values for the startIndex and itemsPerPage?
>>>>
>>>> Thank you!
>>>>
>>>