feat: add API REST pagination doc

[christiannwamba]

Related Issue or Design Document

N/A

Checklist

• I have read the contributing guidelines and signed the CLA.
• I have referenced an issue containing the design document if my change introduces a new feature.
• I have read the security policy.
• I confirm that this pull request does not address a security vulnerability.
  If this pull request addresses a security vulnerability,
  I confirm that I got approval (please contact [email protected]) from the maintainers to push the changes.
• I have added tests that prove my fix is effective or that my feature works.
• I have added the necessary documentation within the code base (if appropriate).

Further comments

N/A

[CLAassistant]

All committers have signed the CLA.

[aeneasr]

Thank you, this looks great! Could you please sign the CLA (just two clicks), then we can merge it right away!

[christiannwamba]

Done. Thank you.

[aeneasr]

Awesome, thank you for your contribution! This looks pretty good and I have some ideas how to improve it further :)

[aeneasr]

The page size is typically dependent on the API and may also change in the future (ie get smaller or larger). There is usually a max page size

[christiannwamba]

Interesting. I couldn't find a max page size value in both the response headers and body of admin/identities. Should I be looking somewhere else?

[aeneasr]

It's only documented in the code at the moment. It's here: https://github.com/ory/kratos/blob/23f323274616c7383668ecb3c405416b8a0e30f0/identity/handler.go#L202

[aeneasr]

Unfortunately, the CI for playwright tests has been failing for some time. I can force merge the PR when it's ready to go :)

[christiannwamba]

Not sure I understand this check that is making the Format task fail:

-- Do not attempt to reverse engineer or make assumptions about the page_token format, as it may change without notice. Always treat it as an opaque string.
+- Do not attempt to reverse engineer or make assumptions about the page_token format, as it may change without notice. Always
+treat it as an opaque string.

[christiannwamba]

@vinckr pointed out it was a prettier thing. Updated

[jonas-jonas]

LGTM.

CI failures are unrelated. And as for the formatting, we have a task running, that ensures all code in all repositories is uniformly formatted. Make sure to run make format if the "Format" task fails, or every time you finalize a change and commit the result. If you use an editor that supports prettier it should format everything automatically, though.

[vinckr]

🚀

[christiannwamba]

Thanks @jonas-jonas