In which order should page- and pageSize-parameters be used?

Question

I'm building an api and a bit into the development I realized that I constantly change the order of the page and pageSize parameters.

Currently I use C# and javascript, so the method declaration looks something like this:

public IEnumerable<Order> Get(int pageSize = 9, int page = 1, string name = null)

And the client code:

this.get =  function (name, pageSize, page) {
    // Do stuff..
}

But a lot of the times I've ended up writing:

name, page, pageSize // note that page is before pageSize.

And it also has an http endpoint, which currently looks like this (with pageSize first):

www.example.org/api/orders/9/1

Or should it look like this (with pageSize last):

www.example.org/api/orders/1/9

What's the logical way to call an api? By setting the page first, or pageSize first? Is there a best (or common) practice?

Argument for setting pageSize first:

• The consumer may simply define the number of items to fetch without setting the page.

Argument for setting page first:

• The consumer may simply shift page and rely on the servers pageSize.

Answer 1

Required on the left. Optional on the right.

If the languages you are using are suffer from a lack of named arguments you have to rely on position. This is the traditional positioning.

There are ways around that. The Josh builder lets you simulate named arguments in these languages.

However, before resorting to that let's review basic telescoping.

Get(String required1, int required2); // A

Get(String required1, int required2, int optional); // B

In C# method overloading allows these to call separate method bodies. Using that you can simply implement A by defining the optional and passing it and the rest to A.

If the default value for the optional is simply a constant then this is a handy way to do it all in one:

Get(String required1, int required2, int optional = 42); // C

However, since 2010 C# has had named arguments. This means callers can avoid the positional confusion by using the names of the arguments they mean when they call.

For you, that might look like this:

Get (name: "MyName", page: 1, pageSize: 9)

Now the order doesn't matter.

This is critically important when there is more than one optional with a default value. Without named arguments you can't pick and choose which optionals to leave with their default values.

In Javascript there is no true overloading but there are some good practices. They also put required on the left and optional on the right.

In URL's folders are usually required. Optionals usually go in the query string. Fan's of semantic URLs might argue against that but if you want it to be optional then you shouldn't require it. A query string lets you have multiple optionals that are named.