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.

What if you just change your URI to /services_devices/{address} and start accepting address in the format you specified i.e. /services_devices/sector.room.group.id ? — JSS, Apr 08 '13 at 17:24
Well, you are really right! I will need to parse those fields, but I think there is no problem.. — user2144555, Apr 08 '13 at 17:31
Is id unique within your application, or only unique within the specified group? In other words, if you provided only /services_devices/id, could you look up sector, room and group? — phatfingers, Apr 08 '13 at 18:08
Yes. For example, 1.1.10.1 regards to a device, and 1.1.21.1 to a different one. — user2144555, Apr 08 '13 at 18:12
My suggestion, deprecate this API and new one or add newer version to this API with correct approach. — Lokesh Gupta, Apr 09 '13 at 06:23

dcernahoschi · Answer 1 · 2013-04-08T18:20:22.217

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...) {
}

Well, now my first approach makes sense, because the `id` represents a device that belongs to a `group`, and that group belongs to a `room`, that belongs to a `sector`. So it is a hierarchy of elements (parameters), and so they can be separated with `/`. Am i right? — user2144555, Apr 08 '13 at 18:23
Yes. Just think if you have more properties for the device, not just "deviceName", maybe you have deviceNumber, owner, etc. If this is the case create and return a `Device` object from the GET method — dcernahoschi, Apr 08 '13 at 18:26

score 0 · Answer 2 · answered Apr 09 '13 at 10:00

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)

RESTful services - how to design a URL with many parameters

2 Answers2