Subject: Re: [scim] Max Results When Listing Resources

From: Shelley <[email-masked]>
Date: Tue, 27 May 2014 15:42:56 -0500

To confirm the expected behavior of pagination and max results, here is my
understanding...

Service Providers are able to limit the number of results returned, even
without filtering [1,2]:

*When specified the Service Provider MUST not return more results than
> specified though MAY return fewer results. If unspecified, the maximum
> number of results is set by the Service Provider. *
>

For example, given 200 users, an SP that does not support filtering, and an
SP with "maxResults" configured to 100:

     "filter": {
       "supported" : false,
       "maxResults": 100
     }

In this case, if a consumer requests all users (/Users), the SP will return
only 100 users. Further, if the consumer requests 150 users via pagination
(/Users?count=150), the SP will return only 100 users.

If this behavior is correct, can the specification be clarified? In other
words, the "maxResults" configuration may not be appropriate as a
sub-attribute of the "filter" attribute and/or some additional text
clarifying this behavior may be beneficial.

[1]
http://www.simplecloud.info/specs/draft-scim-api-01.html#rfc.section.3.2.2.3
[2] http://tools.ietf.org/html/draft-ietf-scim-api-05#section-3.2.2.4

On Tue, Aug 27, 2013 at 2:24 PM, Shelley <[email-masked]> wrote:

> Could anyone provide some clarification on this? Thank you!
>
>
> On Wed, Jul 24, 2013 at 8:25 AM, Shelley <[email-masked]> wrote:
>
>> The Protocol indicates that service providers may limit the max number of
>> results returned when listing/querying resources (described in the
>> Pagination section [1]). However, the Core Schema config resources provides
>> a "maxResults" sub-attribute as part of the "filter" attribute [2]. Since
>> Filtering is optional [3], does the "maxResults" configuration also apply
>> to listing without filtering?
>>
>> [1] http://tools.ietf.org/html/draft-ietf-scim-api-01#section-3.2.2.4
>> [2] http://tools.ietf.org/html/draft-ietf-scim-core-schema-01#section-9
>> [3] http://tools.ietf.org/html/draft-ietf-scim-api-01#section-3.2.2.2
>>
>
>

---

From: Kelly Grizzle <[email-masked]>
Date: Wed, 28 May 2014 14:36:20 +0000

Shelley,

I definitely agree that this is underspecified in the docs.  Ticket #37 (http://tools.ietf.org/wg/scim/trac/ticket/37) addresses this limitation.  The current recommendation in this ticket is to return an error for requests that would return too many resources.

From: scim [mailto:[email-masked]] On Behalf Of Shelley
Sent: Tuesday, May 27, 2014 3:43 PM
To: [email-masked]
Subject: Re: [scim] Max Results When Listing Resources

To confirm the expected behavior of pagination and max results, here is my understanding...

Service Providers are able to limit the number of results returned, even without filtering [1,2]:
When specified the Service Provider MUST not return more results than specified though MAY return fewer results. If unspecified, the maximum number of results is set by the Service Provider.

For example, given 200 users, an SP that does not support filtering, and an SP with "maxResults" configured to 100:

     "filter": {

       "supported" : false,

       "maxResults": 100

     }
In this case, if a consumer requests all users (/Users), the SP will return only 100 users. Further, if the consumer requests 150 users via pagination (/Users?count=150), the SP will return only 100 users.
If this behavior is correct, can the specification be clarified? In other words, the "maxResults" configuration may not be appropriate as a sub-attribute of the "filter" attribute and/or some additional text clarifying this behavior may be beneficial.

[1] http://www.simplecloud.info/specs/draft-scim-api-01.html#rfc.section.3.2.2.3
[2] http://tools.ietf.org/html/draft-ietf-scim-api-05#section-3.2.2.4

On Tue, Aug 27, 2013 at 2:24 PM, Shelley <[email-masked]<mailto:[email-masked]>> wrote:
Could anyone provide some clarification on this? Thank you!

On Wed, Jul 24, 2013 at 8:25 AM, Shelley <[email-masked]<mailto:[email-masked]>> wrote:
The Protocol indicates that service providers may limit the max number of results returned when listing/querying resources (described in the Pagination section [1]). However, the Core Schema config resources provides a "maxResults" sub-attribute as part of the "filter" attribute [2]. Since Filtering is optional [3], does the "maxResults" configuration also apply to listing without filtering?

---

From: Thomas Krille <[email-masked]>
Date: Wed, 28 May 2014 17:11:11 +0200

Hello,

+1 for extending the specification.

i do not think that raising an error when some client requests more
resources than allowed is the right thing to do, because if you restrict
this limit in your SP configuration later you will certainly break clients
that only know about the old limit. imho a better approach is to silently
downsize the response, i.e. if the client request 150 resources but the
limit is 100, just return the 100. the search result contains the number of
returned resources and also the number of total resources. so the client is
responsible and able to understand this downsizing. this is also what we
are doing in OSIAM.

i am aware that every client can get the current limit by just requesting
the current SP configuration. but what are the odds that someone really
does this in production? it also raises more new problems than it solves
(when to update the config? etc.). what do you think?

Best Regards

Thomas Krille
Softwareentwicklung
tarent solutions GmbH

Telefon +49 (0) 30 138803-128
Telefax +49 (0) 228 54881-235
[email-masked]

Rochusstraße 2-4, D-53123 Bonn • http://www.tarent.de/
Tel: +49 228 54881-0 • Fax: +49 228 54881-235
HRB AG Bonn 5168 • USt-ID (VAT): DE122264941
Geschäftsführer: Dr. Stefan Barth, Kai Ebenrett, Boris Esser, Alexander
Steeg

2014-05-28 16:36 GMT+02:00 Kelly Grizzle <[email-masked]>:

>  Shelley,
>
>
>
> I definitely agree that this is underspecified in the docs.  Ticket #37 (
> http://tools.ietf.org/wg/scim/trac/ticket/37) addresses this limitation.
> The current recommendation in this ticket is to return an error for
> requests that would return too many resources.
>
>
>
>
>
> *From:* scim [mailto:[email-masked]] *On Behalf Of *Shelley
> *Sent:* Tuesday, May 27, 2014 3:43 PM
> *To:* [email-masked]
> *Subject:* Re: [scim] Max Results When Listing Resources
>
>
>
> For example, given 200 users, an SP that does not support filtering, and
> an SP with "maxResults" configured to 100:
>
>      "filter": {
>
>        "supported" : false,
>
>        "maxResults": 100
>
>      }
>
> In this case, if a consumer requests all users (/Users), the SP will
> return only 100 users. Further, if the consumer requests 150 users via
> pagination (/Users?count=150), the SP will return only 100 users.
>
> _______________________________________________
> scim mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/scim
>
>

---

From: Shelley <[email-masked]>
Date: Wed, 28 May 2014 10:18:06 -0500

Thanks, Kelly and Thomas.

I tend to agree with Thomas's assessment that it may be better to downsize
the response rather than returning an error.

Based on the current SCIM 1.1 specification, we've implemented pagination
and max results inline with the existing recommendation (as described
previously in the thread), such that our SP may return less results than
requested, rather than returning an error:

> number of results is set by the Service Provider. *

This allows consumers to make a request for the first page of resources
with no pagination params, and then use the resulting "itemsPerPage" to
continue paging through the remaining resources, rather than encountering
an error and having to retry the request with a smaller count.

This also simplifies the expected behavior for the "last page" of results
as compared to other pages. For example, given a maxResults configured to
100:

   - If there are 150 users, would a request for
   /Users?startIndex=100&count=100 return only the last 50 users or fail
   because more resources were requested than exist?
   - If there are 150 users, would a request for /Users (i.e.
   count=unbounded) return only 100 users or fail because more resources were
   requested than allowed?
   - If there are only 50 users, would a request for /Users (i.e.
   count=unbounded) return only 50 users or fail because more resources were
   requested than allowed?

These questions can probably be ironed out and clarified, but "returning
fewer results than requested" conflicts a bit with "returning an error when
too many resources are requested", and this adds a bit of complexity to
these questions.

Also, as Thomas mentioned, this may spark another thread about how dynamic
service provider config values can be. In other words, can an SP passively
update their configured maxResults? Assuming so, returning an error could
require consumers to check this value prior to each request and/or
implement additional retry logic in case the value changes.

On Wed, May 28, 2014 at 10:11 AM, Thomas Krille <[email-masked]> wrote:

>> http://tools.ietf.org/wg/scim/trac/ticket/37) addresses this
>> limitation.  The current recommendation in this ticket is to return an
>> error for requests that would return too many resources.
>>
>>
>>
>>
>>

---

From: Shelley <[email-masked]>
Date: Wed, 28 May 2014 10:49:03 -0500

Is there any concept of "default" versus "max" page sizes?

Some REST APIs have a maximum size for pages (e.g. 100), but default to a
smaller page size (e.g. 20) when no specific count is provided.

Given that the SCIM specification makes no mention of default page sizes,
only maximums, our SP currently makes no differentiation between these;
when no "count" is specified, we simply return the maximum number of
results. In my opinion, this approach keeps responses simple, predictable,
and consistent, rather than differentiating, which really provides minimal
value in REST APIs (unlike web UIs). If consumers want less than the
maximum, they can provide the "count"; otherwise, if they want as many
resources as they can get, they can omit the "count."

Just curious if there are any other guidelines or opinions on this matter,
which also relates to how requests with no "count" are returned (i.e. would
a default page size be returned, or would the max page be returned, or
would an error be returned?).

On Wed, May 28, 2014 at 10:18 AM, Shelley <[email-masked]> wrote:

> On Wed, May 28, 2014 at 10:11 AM, Thomas Krille <[email-masked]>wrote:
>
>> Hello,
>>
>>> If this behavior is correct, can the specification be clarified? In
>>> other words, the "maxResults" configuration may not be appropriate as a
>>> The Protocol indicates that service providers may limit the max number
>>> of results returned when listing/querying resources (described in the

---

From: Phil Hunt <[email-masked]>
Date: Wed, 28 May 2014 08:52:00 -0700

Just trying to think where this might have an impact on some clients...

Anybody doing partial (as user types) searches? In this case I can see a difference. You want an error while search is still too course. Returning partials can be noisy if filter is poor. 

Phil

> On May 28, 2014, at 8:18, Shelley <[email-masked]> wrote:
> 
> I tend to agree with Thomas's assessment that it may be better to downsize the response rather than returning an error.
> 
> Based on the current SCIM 1.1 specification, we've implemented pagination and max results inline with the existing recommendation (as described previously in the thread), such that our SP may return less results than requested, rather than returning an error:
> 
> This allows consumers to make a request for the first page of resources with no pagination params, and then use the resulting "itemsPerPage" to continue paging through the remaining resources, rather than encountering an error and having to retry the request with a smaller count.
> 
> This also simplifies the expected behavior for the "last page" of results as compared to other pages. For example, given a maxResults configured to 100:
> If there are 150 users, would a request for /Users?startIndex=100&count=100 return only the last 50 users or fail because more resources were requested than exist?
> If there are 150 users, would a request for /Users (i.e. count=unbounded) return only 100 users or fail because more resources were requested than allowed?
> If there are only 50 users, would a request for /Users (i.e. count=unbounded) return only 50 users or fail because more resources were requested than allowed?
> These questions can probably be ironed out and clarified, but "returning fewer results than requested" conflicts a bit with "returning an error when too many resources are requested", and this adds a bit of complexity to these questions.
> 
> Also, as Thomas mentioned, this may spark another thread about how dynamic service provider config values can be. In other words, can an SP passively update their configured maxResults? Assuming so, returning an error could require consumers to check this value prior to each request and/or implement additional retry logic in case the value changes.
> 
> 
> 
> 
>> i do not think that raising an error when some client requests more resources than allowed is the right thing to do, because if you restrict this limit in your SP configuration later you will certainly break clients that only know about the old limit. imho a better approach is to silently downsize the response, i.e. if the client request 150 resources but the limit is 100, just return the 100. the search result contains the number of returned resources and also the number of total resources. so the client is responsible and able to understand this downsizing. this is also what we are doing in OSIAM.
>> 
>> i am aware that every client can get the current limit by just requesting the current SP configuration. but what are the odds that someone really does this in production? it also raises more new problems than it solves (when to update the config? etc.). what do you think?
>> 
>> Best Regards
>> 
>> Thomas Krille
>> Softwareentwicklung
>> tarent solutions GmbH
>> 
>> Geschäftsführer: Dr. Stefan Barth, Kai Ebenrett, Boris Esser, Alexander Steeg
>> 
>>