REST API Design – How to Check if Email is Unique

apiapi-designrest

We need to have an endpoint that allows us to check if a user's email is unique. This operation doesn't seem incredibly RESTful and we're struggling to figure out how to make it fit. We've been debating on whether we should make this more of an RPC style endpoint that might look like the following:

URL

GET identities/check_email

Response

{
  "ok": false,
  "error": "taken"
}

The rub being this doesn't fit incredibly well with everything else we're doing.

We've also considered sending a HEAD request but we're not quite sure what that would look like.

Best Answer

Use the HEAD verb. If GET /identities/joe@example.com would return either 200 Okay with JSON about Joe or 404 Not Found, then HEAD /identities/joe@example.com acts the same as GET but only returns the headers and status code. You can use HEAD as an "existence check" for an arbitrary resource (presuming the server hosting the resource properly understands the HEAD verb).

This presumes individual users are resources and are identifiable by email. If you currently only support identifying user by IDs such as /identities/123, you could add an /identities/emails/{email} route which either returns 404 Not Found or redirects to the matching user's URL.

Related Topic