API naming for limiting results?

Question

At our office, we are having heated discussions regarding naming some arguments in our public API.

Everywhere we are providing getters to lists of some kind, we want to be able to limit results (for pagination).

Ie: getPosts/getNews/getUsers/.../ should be able to return items 0 to 25, 50 to 100 etc. So, we need two parameters. First parameter is where we start, and second parameter is where we end.

So, should the second parameter be absolute or relative? (Should 50,75 return items 50-75 or 50-125?)

We have decided on relative, so the second parameter tells us how many items to return.

The tricky part is naming this in a clear and consistent way. The ones we have come up with so far:

First:

start/index/offset/page/pageindex

Second:

amount/count/maxcount/limit/perpage/pagesize

There are pros and cons to every suggestion. Using "page" would make it unclear on whether it starts on 0 or 1. Using "index" or "offset" would be clearer in that regard, but more technical (after all, users are using this for pagination in 99% of the time).

I guess this is highly subjective, but Im looking for clear pros and cons, and possibly examples of good APIs and what they are using.

Answer 1

I would go for relative, it's easier to grasp.

regarding the naming: I like "start" for the first result and "count" for the number of results.

(but aren't you somehow mixing page and results counts?)

Answer 2

Definitely go relative. I'd call them "index" and "count". Normally I'd use "length", but it doesn't seem to fit for what you're describing. If you want to make it similar to linq, you could call the parameters "skip" and "take". These terms are also more approachable for the Joe Average guy who's going to be looking at the resulting URL.

Answer 3

I would go with

getPosts(startIndex, count)