JAX-RS/Rest: Set a parameter multiple times, or use a single comma-delimited parameter?

Question

I read that the HTTP way to pass an array in a request is to set a parameter multiple times:

1) GET /users?orderBy=last_name&orderBy=first_name

However, I've also seen the comma-delimited parameter (and I feel this is "cleaner"):

2) GET /users?orderBy=last_name,first_name

I want to implement multi-sorting (ordering users by last_name, then duplicate last_names are ordered by first_name). Code-wise, this is easy (Google's Guava libraries to the rescue), but how should I expose this? Does the first way even preserve the order of the fields (sort by last_name, then by first_name)?

Spring will magically convert a parameter into a String[] array, if it is set multiple times in the request:

... @RequestParam("orderBy") String[] orderBy ... becomes ["last_name","first_name"]

This leads me to believe the first way is considered best-practice, although I like the second way...

Answer 1

I think it's a matter of opinion. JAX-RS allows you to have parameters like:

@QueryParam("orderBy") List<String> orderBy

which I think would do the same thing as Spring regarding "magically convert" part. I don't necessarily think this is indicative of a "best practice" or not. It's just that some parameters can have multiple values and the frameworks allow you to read those multiple values (think certain HTML forms).

Personally, I would use a single value that's comma delimited. It's "cleaner" like you said and the value is easier to build (you're not relying on the order of parameter key/values which can lead to some trouble for client developers).