Default pagination recommendation now cursor-based

[ca0abinary]

PR for discussion at #25

• Change pagination recommendation to cursor-based
• Include language that all APIs MUST include cursor-based pagination
• Add additional documentation about the use case of API sorting + pagination types
• Add additional documentation about how Offset and Cursor pagination is used at the same time

@mkokotovich and @travisgosselin - maybe you have some recommendations on the additional documentation items?

Also, we had discussed including language that all APIs must (as a requirement) implement cursor pagination. Does that make sense for simple/static APIs as well?

[travisgosselin]

Thanks @ca0abinary for submitting this. It was tough to review with all the extra linting you did. Consider in future PRs doing linting in separate PRs to keep it easy to review core standards changes.

Also, we had discussed including language that all APIs must (as a requirement) implement cursor pagination. Does that make sense for simple/static APIs as well?

Generally yes we want cursor-based paging always now for simplicity. But I'm with this being a SHOULD scenario... as that still captures the cases we want to cover.

Added a few inline notes, but also I would add a new section that demonstrates what Cursor and Offset paging look like together. The same example above may be combined with including API Sorting at the same time, like a master example almost at the end of how it all comes together.

[ca0abinary]

Thanks @ca0abinary for submitting this. It was tough to review with all the extra linting you did. Consider in future PRs doing linting in separate PRs to keep it easy to review core standards changes.

Consider using the hide whitespace feature to simplify your reviews. 😄

[travisgosselin]

Consider using the hide whitespace feature to simplify your reviews.

Nice thats amazing. Thats a great pro tip :)

[travisgosselin]

Let us know when we should have a look at this PR again @ca0abinary . Just didn't want to add comments if you in the middle of working through changes, adding the other bullet points, etc.

[ca0abinary]

Let us know when we should have a look at this PR again @ca0abinary . Just didn't want to add comments if you in the middle of working through changes, adding the other bullet points, etc.

Thanks, I think it's ready for another review!

[travisgosselin]

In general, I think this is the minimal set of changes needed to enact the transition to cursor-based pagination as the default. I'd be in favor of merging this. However, just wondering about some of the other items on your checklist... if there was still a desire to implement some of them, or if you were thinking they were separate PRs now or not needed at all?

[ca0abinary]

However, just wondering about some of the other items on your checklist... if there was still a desire to implement some of them, or if you were thinking they were separate PRs now or not needed at all?

I think it might be good to break those into another PR. I haven't personally spent time building APIs to this spec so my lack of experience might hinder me from providing good guidance.

[travisgosselin]

Sure, that sounds good. Thanks for making this change!