RESTful services - how to design a URL with many parameters

Question

I've developed REST services, but now I realized that I'm doing something wrong.

For example, I have a service which retrieves information about a specific device. Each device has an address: sector.room.group.id . The URI I did for this GET method was: (...)/services_devices/{sector}/{room}/{group}/{id} But now I realized that I should not have used the '/' to separate the device address, right? How should I pass the address to this method? Using ';' ?

My GET method is:

@GET
@Path("{sector}/{room}/{group}/{id}")
@Produces("application/json")
public String getDeviceName(@PathParam("sector") int sector, @PathParam("room") int room, @PathParam("group") int group, @PathParam("id") int id) throws Exception
{
    String name = null;

    try {
            name = new DevicesManager().getDeviceName(sector, room, group, id); 
    } catch (Exception e) {
            e.printStackTrace();
    }
    return name;
}

There is a simple way of change this, to have a correct URI? I have this "error" in many methods.

Answer 1

If there is a hierarchy in your resources path variables are appropriate.

It seems in your case there is a hierarchy between devices and address, but first comes the address and after the deviceName. "deviceName" can be considered a one more hierarchy step.

The best way to reflect the above relations would be the following url:

(...)/sector/room/group/id/deviceName

You can then have another attribute of the device mapped like this:

(...)/sector/room/group/id/deviceOwner

The JAX-RS mapping would be:

@GET
@Path("{sector}/{room}/{group}/{id}/deviceName")
@Produces("application/json")
public String getDeviceName(@PathParam ...) {
//impl.
}

And yes, if the deviceName is the only relevant attribute of the resource, then you can leave out "deviceName" and your orignal mapping is correct.

If the resource at /sector/room/group/id has many attributes you should consider returning a composed object for the path:

@GET
@Path("{sector}/{room}/{group}/{id}")
@Produces("application/json")
public Device getDeviceName(@PathParam...) {
}

Answer 2

REST architectural style introduces HATEOAS, which means that client and server are loosely coupled. Simply the client is not aware of how the URLs look like and gets them from previous responses. (it's similar like surfing thru HTML pages). Of course there will be at least one URL, an entry point, that is known to the client. From this point of view, your need to have correct URIs is irrelevant. What's correct URI? The URI is correct when its form is aligned with RFC.

You are probably introducing URL patterns, that are not RESTful, because it implicates tight coupling between client and server (the client must be aware of URL patterns and have ability to construct URLs from them; fill up sector/room/ etc. in your case)

See also this post:

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

My advice is; don't waste your time on URL patterns, make URLs simple as is possible, flat hierarchy has also many benefits, and follow HATEOAS principle.