REST path design for resources having multiple IDs

Question

I'm trying to define the API for the REST paths of a new service where I have devices, and each device has a current location.

It needs a bit of background to understand the problem:

• This is about pushing current device locations to a central server
• Position updates are sometimes calculated on the device itself (GPS) and sent from the device (smartphone) to a server, but sometimes also via an external service (e.g. WiFi positioning system) and send from that system to a server
• Each device has a unique id which the smartphone knows. The WiFi positioning system cannot know this id, it just knows the WiFi mac address.
• Each device has several interfaces for position updates (mac addresses)
• Regardless of where / from which interface location updates come, all location data should be linked to the same unique device id

So much for the background. Now about the API design. As mentioned above, I may get location updates where only the mac address is known, and I may get location updates where the unique device id is known. In both cases I can assume the id I get is unique and theoretically I can say that mac address x belongs to device y. Practically, this means I have a non-unique index to my location REST API:

For an example, consider I have a device with ID "123" and two mac addresses "abc" and "xyz". Commonly, my REST API path would group locations under the unique device:

/devices/$id/location

Now the problem is that there are multiple (unique) ids, each however related to one same device.

Like for example this would push a location by unique device id from the smartphone (where I know that unique ID, but do NOT know the mac address of the interface):

PUT /devices/123/location

And this is where an external system which only knows the mac address is pushing the location update using the mac address as key:

PUT /devices/abc/location
PUT /devices/xyz/location

You can assume that internally I can relate mac addresses and unique device IDs to one unique internal device. I could update and return location and device info using either a mac address and a device id.

For example the following GET requests using either the unique device id or unique mac will return the same location object:

GET /devices/123/location
GET /devices/abc/location
GET /devices/xyz/location

But is that a valid REST design where I can have multiple paths to the same resource? Should I rather change my REST paths, and how?

Answer 1

It might be useful to think about how you would design a web site that supports this behavior...

You might design that protocol this way: the client loads a known bookmark URI. Available in the representation of that page are two links, one for clients that know the mac address, a different link for those that know the identifier. The client would choose the appropriate link to follow. The representation returned by that would be a form, customized for the specific use case; the description of the form would specify the expected fields. The client would fill in the known fields (ignoring any unknown fields, which presumably have reasonable default values), and submit the form. The browser would use standard processing rules to produce the appropriate HTTP request to the action specified in the form.

In this case, where what we are interested in is (effectively) looking up the URI of the resource we want based on the information we have, we would normally use GET as the form method. That would send a query to the server, and from there the server can communicate (perhaps via re-direct) the appropriate URI to use for that device.

Once you've got the correct URI to use, GET/PUT/POST/PATCH/DELETE should all work as you would expect.

is that a valid REST design where I can have multiple paths to the same resource?

If the identifiers are different, then the resources are different. You are, of course, allowed to have more than one resource that expresses some concept (or, to put it another way, two different resources are allowed to share a single semantic mapping).

For your specific case, it would probably be OK to have a resource for clients that know the device by id, and another for clients that know the device by location. However, sharing a single resource identifier for both cases simplifies the server side caching story.

Part of the point of REST: if you define your media types and relations carefully, the server should be able to change the caching strategies used without breaking any clients (because the clients are just following links and submitting forms provided by the server).