When I look at the API Doc, for example here: https://www.ory.sh/docs/reference/api#tag/identity I see a parameter page described as:

integer <int64> >= 1
Default: 1
Pagination Page

This value is currently an integer, but it is not sequential. The value is not the page number, but a reference. The next page can be any number and some numbers might return an empty list.

For example, page 2 might not follow after page 1. And even if page 3 and 5 exist, but page 4 might not exist.

First of all, this is wrong. page starts with 0 not 1, so >= 0 would be correct. But how can I properly use paging, when intermediate pages could be “missing”? How do I know what the next page is? And is at least page=0 always the “first” page? How do I go from there to ensure I get all entries?

so not including a page gives you the first one, the next one is in the

Link

header

Sounds simple enough. But this is really now what I find in the documentation. Would be nice to update that accordingly. And are page_size and per_page synonyms for limit, that should not be used anymore?

ah hm not sure what the correct limit parameter is, let me check

limit does not work.

ok then that one

page_size does as well.

sure, I'm on it already

@steep-lamp-91158 This page is still outdated/wrong: https://www.ory.sh/docs/ecosystem/api-design And in the Pull Request you deprecated the x-total-count header. Why is that deprecated? It’s useful to show proper paging info, like: 1-50 of 2405 entries, as shown in you own console UI. Or how else can the total amount of entries be retrieved?

it will need some time to propagate

Understood. It’s still a nice info to know how many entries there are in total, independent of the page I’m retrieving. I look at the total number of users sometimes to check things. It’s not super critical, but useful. But it’s your decision to provide it or not. If I can’t retrieve it (maybe through an explicit call?), I would have to page through all users to determine how many there are, which is even more load and not really feasible, because it takes really long.

yes exactly, we will add separate APIs or add a parameter to allow getting a total count, but only when explicitly requiring it