Java REST service PUT parameters

Question

This is how my Jersey Rest web service's a few methods looks likes, I have some methods to update the user settings like:

@PUT
@Path("/langauge")
@Consumes("text/plain")
public void updateLanguage(String lang) {

    ***check validity of the lang by string comparisons**
     and update database with the new language*
}

@PUT
@Path("/threshold")
@Consumes("text/plain")
public void updateThreshold(Long threshold) {

   *//check value and update in server*
}

Now I have a few questions here;

1- Instead of different resource paths for different update options, is it better to create one resource and update with query parameters? This looks more Restish but I'm not sure I really should change it to something like, because in future if there are more parameters to be updated than it will be very cluttered, while having independent paths looks more clear?

@PUT
@Path("/settings/{lang}/{threshold}")
@Consumes("text/plain")
public void updateSettings(@PathParam("threshold") String thre,
        @PathParam("lang") String lang,
        @DefaultValue("") @QueryParam) {


}

2- Another question is while updating the language now I accept a language as a string then check if thats valid or not in server, So when client uses this method they don't know what exactly should they send as valid parameters. Is there a way to make this more user friendly, putting some comments on WADL file is an option, but is there another more REST way of doing this?

Answer 1

Without knowing the entire scope of your application, I'd say, you could consider the settings a resource and the particular options as the member of the collection of settings. This would allow to add new settings (downside is, that a client that wants to update multiple would need to know and call all of them):

/settings/language
/settings/threshold
...
# later
/settings/timeout
/settings/temperature

You could implement the GET method on each of the options to display information to the interested client (either as HTML or text or some other format).

Another way would be to collect all settings at one endpoint and to accept a request entity in some format (eg JSON) as a representation of all available settings. This approach can be observed in the wild in the elasticsearch APIs (eg here: http://www.elasticsearch.org/guide/reference/api/admin-indices-update-settings.html ).

Answer 2

Answers :

1) Since they are separate resources, they should have separate service methods. So the earlier approach is great. That makes your code flexible.

2) You can give unique IDs to each of your resources (language in this case) and use it to update the language like:

api/language/{languageId}

This ID could them be auto-generated through the database or you could define some other mechanism.