Refactor pagination API

[ahmednfwela]

the current pagination API is confusing, and leads to alot of bugs for the following reasons

1. the pagination inputs are repetitive, e.g. you have hitsPerPage and limit which are the same thing, also offset and page are used to calculate the same thing
2. different inputs lead to different outputs, when you send page you get a page result , and when you send offset you get search result
3. using the page api is just opting for more accurate total at the cost of slower search

so I suggest the following changes:

1. remove page and hitsPerPage
2. introduce a new bool parameter "accurateTotal" which if true, will opt in for the accurate result over the slow performance
3. merge page result and search result into just search result, with a totalHits and totalPages in the same response.
4. introduce methods in the sdks to help convert one-based page indexes to zero-based offsets based on the limit, and vice versa.

[macraig]

Hi @ahmednfwela , thanks for submitting your feedback about our pagination API.

We certainly know the current API is not perfect, and we've had several internal discussions about it ourselves. In the past, we used to only offer a non-exhaustive / approximative pagination via the offset / limit parameters. A lot of users were frustrated about it, and that's why introduced the finite pagination option.

At that time, we chose not to break the previous pagination and to offer two different ways of doing it to reduce the pressure on users to be up to date and force them to deal with breaking changes. We can however take your feedback into account for our next major version 2.0 (as we won't introduce breaking changes while we're still on v1). For example, we could have a Boolean to choose which pagination method to use, like, finitePagination and still use the same set of parameters. What do you think?

[ahmednfwela]

@macraig yes I think this is perfectly fine !