Is it OK to use email as an identifier in a RESTful URI?

Question

I'm working with a team building a RESTful web service, and our current implementation utilizes the user's email as a unique identifier for the user resource, yielding URIs like the following:

https://www.domain.com/users/[email protected]/resource

Emails are guaranteed to be unique in our system, and we've handled when the user changes his/her email, so it seems OK. But is it correct? The debate is whether we should use an immutable user ID instead, which in our case would look more like:

https://www.domain.com/users/a36571b87be464728c8d/resource

Or perhaps something else altogether. For instance, several Google APIs simply use /users/me/resource and identify the user via auth data.

In a nutshell, is it acceptable to use a unique but mutable identifier in our URIs, or should we use an immutable one?

Thanks!

Answer 1

There are two sub-questions to your question:

1. Can I use unique but mutable identifiers in my URLs?

   This can work well if either the IDs change only infrequently or if the URLs containing those IDs are not used outside your site. As REST APIs usually are built on the premise that any given URL can be re-used to access the same resource at any later time, that second condition goes a bit against the idea of REST.

   That leaves the probability of changes to the ID and if you are willing/able to redirect requests made using an old ID. With (encoded) email addresses, this can probably be realized, because an old email address will not be re-used by a different user that often.

2. Can I use email addresses as my unique ID?

   As indicated by the answers of @LucFranken and @9000, using a plain email address in your URL is a bad idea, but you can use an 'encrypted' form of an email address as ID. This 'encryption' can be as simple as base64 encoding.

Answer 2

users/me feels like a bad idea because REST prefers to have one url per resource. You will then have:

users/me users/123myId

Which point to the same resource. If you work with hateos better supply a link to your own resource.

Then about the e-mails: An URL should, in my opinion, not have confidential or private data in it. For example: The url can be used for logging, caching etc. That creates a place where one or more e-mailaddresses are listed.

Those could be used for spam, login attempts, etc.

See also: https://stackoverflow.com/questions/499591/are-https-urls-encrypted

So, no I would not do that.

2016: Answer to comment:

Let's agree that we walk about urls / uris at this point. Not exactly the same, lookup the difference. Roy Fielding is mentioned a few times below, he is the inventor of REST https://en.wikipedia.org/wiki/Roy_Fielding and other related technologies.

In general it's written as: Url to identify a resource. I take that as: One resource one url but it's not a hard rule.

https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm part 5.2.1.1 is interesting on this topic. "REST relies instead on the author choosing a resource identifier that best fits the nature of the concept being identified". So you have the freedom to choose, so why not chose multiple urls for the same resource?

For this specific case:

https://www.ics.uci.edu/~fielding/pubs/dissertation/evaluation.htm#sec_6_2

Part: 6.2.5 "One form of abuse is to include information that identifies the current user within all of the URI referenced by a hypermedia response representation."

I got lucky and found a quite specific answer to this case as you can see above. The same part also discusses some of the caching issues which might occur.

In general on REST and urls: I did not find proof that one resource === 1 url. But, in practice, I don't like it. You will have multiple urls which is less clear: "Here you can find that resource, but also here, and here.". In HATEOAS what will you define as the link to _self? An array of urls?

W3 posted an interesting post on the use of urls: http://www.w3.org/TR/cooluris/#intro

Stability. Once you set up a URI to identify a certain resource, it should remain this way as long as possible. Think about the next ten years. Maybe twenty. [...]

Much more interesting to read in that post where you can find numerous argument to keep urls stable.

And: http://www.w3.org/Provider/Style/URI on "I didn't think URLs have to be persistent - that was URNs."

BUT: Now let's just focus specifically on REST, because urls are much wider used as seen in the previous articles.

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

A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC’s functional coupling].

So, server informs the client on the right urls to use. No guessing around what the url should be, server tells. Either by supplying hard urls or by providing url templates: https://www.rfc-editor.org/rfc/rfc6570. So in that sense it doesn't matter too much, your clients will still work even when the server changes url structure.

That also removed part of the advantage of having 2 urls for the same resource, say /customers/1 and /user/123/customer/1 because it's not something a human should interpret and/or change by himself.

Then in the comments on that post by Roy Fielding:

A truly RESTful API looks like hypertext. Every addressable unit of information carries an address, either explicitly (e.g., link and id attributes) or implicitly (e.g., derived from the media type definition and representation structure).

and:

Any important resource in a RESTful system must have an identifier [...]

That, to me, is kind of enough direction into keeping one url per resource. So to summarize: I did not find a strict hard rule but the intention and advantages of having one resource === one url to me are enough to stick to it. Advantages of having multiple urls don't seem to be available a lot except when you start to manually craft urls which does not seem to be the intention.

For more answer you might pose this question to Roy Fielding himself.

Answer 3

The idea seems fine, as long as it handles various valid types of email addresses one might encounter. I, for one, routinely use emails like account+purpose@domain; there are many more cases.

Maybe using canonicalization and then URL-encoding or even base64 on the email before using in URLs is a good idea.