Pagination Options & Support

[mkokotovich]

I was reading https://spscommerce.github.io/sps-api-standards/standards/collections.html, specifically the section around pagination. As it is currently written, it recommends using limit/offset as the preferred method, and then cursor-based pagination if required by performance concerns.

I am a fan of limit/page (or pageSize/page, etc) as well. It maps well to how the consumers often use pagination (to display multiple pages of results on a UI).

I also have noticed that other companies support cursor-based pagination as the primary method, and then may or may not support limit/offset or pageSize/page in addition. I wonder if we should recommend that all APIs support cursor-based pagination.

[travisgosselin]

Great feedback!

For reference, the original reason(s) that offset pagination was suggested as the preferred default was mostly aligned to the "lowest common denominator". Most teams at SPS Commerce ARE NOT doing cursor-based pagination (some are though, like Transaction API). The reality that I'm perceiving is that the volume and frequency of data for many APIs at SPS on resources that have pagination do not suffer from performance issues. This could mean that the granularity of data and volume for a designed service will never result in problems, or it's a problem that will come in the future for some services as they grow.

We also referenced industry-similar APIs, many of which use offset, e.g. https://developer.walmart.com/api/us/mp/orders#operation/getAllReleasedOrders Though by no means do I think this is a great criterion to make decisions on the Standards.

Many teams who are unfamiliar with cursor-based pagination and with services that do not require its advantages may suffer some velocity loss over-burdening them with a required pagination mechanism. To a larger degree, this is why simple and advanced filtering exists as well. The same could be said for offset-based (simple) and cursor-based (advanced). However, to be fare, the degree of difference in pagination implementation from a technical standpoint seems far less burdening than the differences in filtering implementation.

In previous discussions, @alexander-ivakhnenko points out, and your suggestion as well @mkokotovich, it does seem like there is a shift in cursor-based pagination being the default standard in the industry for the major APIs we look at as examples:

The advantage of course in moving in that direction as well would be to offer a consistent paging mechanism/contract that was guaranteed across our API platform, with some APIs implementing offset-based pagination potentially when needed, rather than most APIs implementing one or the other without consistency.

Additionally, this has the advantage of ensuring we do not have breaking API contracts in an API as it begins to discover performance issues over time. While cursor-based pagination can be added in a non-breaking way, it is difficult to remove the old pagination method which may have performance degradation. It also makes it a bit ambiguous which URLs are provided in the "paging" response model (offset-based URLs or cursor-based URLs) by default (that being said, this kind of non-breaking transition is the promise of hypermedia). See some thoughts on Shopify's transition: https://shopify.engineering/pagination-relative-cursors

Some additional examples and support for reference:

• Microsoft - doesn't indicate pagination type as long as it is hypermedia / opaque token (https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md#98-pagination)
• CloudFoundry - uses pages - https://github.com/cloudfoundry/cc-api-v3-style-guide#pagination
• CiscoDevNet - uses offsets - https://github.com/CiscoDevNet/api-design-guide#363-get
• Atlassian - uses offesets - https://developer.atlassian.com/server/framework/atlassian-sdk/atlassian-rest-api-design-guidelines-version-1/

It is also worth noting the original SPS DevCenter standards actually do indicate the preference for cursor over offset as well: https://developercenter.spscommerce.com/#/docs/api-standards/pagination.

Cursor-based pagination works with mostly unique indexes or fields of data to key off. This would not work for requesting data that can be sorted on additional columns as part of the API (unless built into the cursor opaque URL and all fields were largely unique - which would be unlikely). This is a good representation where if APIs had this requirement, would they then be required to implement both? or just offset?

Trying to distill the above content into direct questions/answers:

• Should Cursor-based pagination be the default option (Original Topic Question)?
  I'm leaning towards the idea that cursor-based pagination should be the preferred option unless you require offset-based pagination features. This it would seem is the best advice for API delivery teams long term, given the implications of not using them. However, I'm not sure I see a direct correlation that cursor-based pagination is a better developer experience "generally speaking". Thoughts?

• Does the scale and size of SPS Commerce warrant that ALL APIS MUST (as a requirement) implement cursor pagination?
  I worry that what you are actually calling out @mkokotovich is the need for us all to consistently use cursor pagination to meet the goals of a consistent developer experience and we would need a more heavy-handed statement to say you MUST implement cursor-based pagination to make that happen. However, I also want to avoid following suit with references like Microsoft, Googles, Slacks of the world if their requirements and size of data are beyond any short/medium-term requirements we have. Thoughts? Does anyone have concerns here?

• Should we add additional documentation about the use case of API sorting + pagination types?
  YES!

• Should we add additional documentation about how Offset and Cursor pagination is used at the same time?
  YES!

[eggilbert]

I'm familiar with the concept of cursor pagination and its advantages, but I've never implemented it before so I was curious how it works with sorting and more specifically when the sort key has duplicate values or otherwise isn't the uniquely increasing thing to cursor/range scan across.

This article did a good job explaining how that would need to work under the hood: https://shopify.engineering/pagination-relative-cursors

Before we flip the default recommendation we should be sure to fully understand the impact on how that will affect the implementation of things, as it seems like there's more nuance here than just functionality loss in UI controls. (Not saying changing the default is a bad idea, just that we should fully understand the impact and make sure we aren't losing something else that is important.)

[cnordhougen]

When it comes to our pagination UX patterns in Woodland Design System, we can support whichever pagination scheme. True, the way it is being used in many of our apps does allow you to type in an arbitrary page number and jump there, but we don't know how much that functionality is being used in reality. My gut says that users are probably just using the next/previous page buttons. The other need to consider is being able to send someone else a link to a particular page of results so they can see what you're seeing - however this could be achieved with a cursor location param rather than a page param.

[travisgosselin]

@eggilbert - Completely recognize where you're coming from. Using cursor-based pagination has some interesting edge cases on certain data I'm sure you thinking of. That article walks through some of it. To date, we have tried to keep the API Standards away from talking about implementation, but I think some of the discussion bleeds into both. So there is probably a couple "rule of thumb" callouts we can make in the API Standards documentation to at least direct individuals down some paths.

@cnordhougen - as you describe it was our thought process as well. The API Standards already provide an indication from an API level how to handle cursors in the query parameters, and that functionality could be proxied through a deep link in a UI app for sure for passing along deep link references. Glad to hear there is no concern on supported scheme from a woodland perspective.

Sounds like we are ready to convert this to an issue and begin some more concrete proposed updates.

[travisgosselin]

@ca0abinary is going to put together a proposal PR for further discussion on the above changes. @mkokotovich hoping you can support here as necessary.

[ca0abinary]

To wrap up the discussion:

Should Cursor-based pagination be the default option (Original Topic Question)?

• Yes

Does the scale and size of SPS Commerce warrant that ALL APIS MUST (as a requirement) implement cursor pagination?

• Yes

Should we add additional documentation about the use case of API sorting + pagination types?

• Yes

Should we add additional documentation about how Offset and Cursor pagination is used at the same time?

• Yes