REST - supporting multiple possible identifiers
For the site I am working on, we are in the process of improving our URLs for one type of resource - specifically, moving away from numerical IDs toward unique, descriptive strings. A similar example would be switching from identifying users by numerical database ID to identifying them by username (not our specific case, but analagous). So a URL to access a user's information used to look like:
/users/48573
And now it looks like
/users/thisisausername.
The only problem is that we still need to be able to fetch them through numerical IDs somehow, for legacy consumers of the API. We don't need the REST URLs themselves to redirect (e.g. /users/48573 should not redirect to /users/thisisausername), we just need a method to obtain the right data using the old identifier. The solution should either provide an alternate way of accessing the user information (which conveniently includes the new identifier, username) by ID, or of accessing just the username by ID. Some possible solutions might be:
- Using a node to specify some alternate method of identification, e.g.
/users/byid/48573 - Using a query parameter to specify some alternate method of identification, e.g.
/users/48573?fetchby=idor/users/48573?byid=true - Treating username-by-id as another resource, e.g.
/identifiers/username/48573
Which of these (if any) is closest to proper REST? How would you deal with the problem?
I think adding a path segment/prefix is the best answer. Since these are unique secondary keys, this isn't the same as search (which returns a set of items), so using query parameters (which aren't cached) doesn't seem like the best choice.
Personally, I plan to use a path segment prefix delimited by "=", like "name=" or "email=":
user/123456
user/name=john.doe
user/[email protected]
This is functionally equivalent to adding a path segment (e.g. "user/name/john.doe"), but feels to me like it maps more closely to the conceptual model. Of course, this is an insignificant detail, since RESTful APIs shouldn't specify a fixed URI structure anyway.
Not using query parameters also allows sub-resources to be accessed naturally:
user/name=john.doe/inbox/df87bhJXrg63
Frameworks like Java's JAX-RS support using whatever delimiter you want:
@GET
@Path("user/{id}")
User getUser(@PathParam("id") UUID id);
@GET
@Path("user/name={name}")
User getUserByName(@PathParam("name") String name);
@GET
@Path("user/email={email}")
User getUserByEmail(@PathParam("email") String email);
Your first option is probably the best.
Searching for users by ID:
/users/id/48573
Searching for users by short name:
/users/name/thisisausername
If they leave out that path parameter, you could always default to your new short username format.
Another option that I have seen quite a bit is to use query parameters like the following:
/users?id=48573
/users?name=thisisausername
I think the first looks a bit cleaner and more readable.