SCIM Cursor Pagination

SCIM clients can obtain the set of resources managed by the SCIM service provider and request that the provider deliver the resources sorted, filtered, and paginated.

There are two common patterns for result pagination: index-based and cursor-based. 

• Index-based: The client provides the numerical index of the first item to retrieve and the maximum number of items the client is prepared to receive.
• Cursor-based: the client initially provides an empty cursor value and the maximum number of items the client is prepared to receive. The service provider returns items and a next-cursor value for the client to obtain the next page of results. The next-cursor value could be a set of hex values, a number, or whatever the service provider needs to resume. The service provider can also return a previous cursor to allow the client to go backwards.

The SCIM protocol only supports index-based pagination, which can be problematic since it is an interop protocol connecting existing systems. As such, existing systems, such as graph APIs, may not be able to efficiently deliver index-based pagination.

To address this, the SCIM working group has created a draft SCIM Cursor RFC to extend the protocol and support cursor-based pagination. The draft is now in version five, and to ensure we are ready for when it is accepted, we have implemented it in version 6.0 of our SCIM component. 

Before making a GET call, clients must know what form of pagination an SCIM service provider supports. They can obtain this information by first interrogating the ServiceProviderConfig endpoint.

If the server does support cursor-based pagination the client could then make cursor-pagination calls

Examples

GET /Users?filter=userName%20sw%20J&cursor&count=10

GET /Users?filter=username%20sw%20J&cursor=VZUTiyhEQJ94IR&count=10

As part of our implementation, we have provided an adapter that makes it easy for stores currently implementing index-based pagination to implement cursor pagination. This adapter seamlessly converts cursor-based requests to index-based ones, ensuring a smooth transition, minimizing potential disruptions, and allowing clients only to support cursor-based pagination if desired.

Hopefully this RFC will be approved soon, making it easier to implement SCIM service providers for non tabular data stores.