Proper route for checking resource existence in a RESTful API [closed] - api

Question

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
What's the best/restful way to design an API endpoint for checking existence of resources?
For example there is a user database. While new user tries to sign up I want to check if email has been used on-the-fly.
My idea is: POST /user/exists and payload would be something like {"email": "foo#bar.com"}. The response would be either 200 OK or 409 Conflict.
Is this a proper way?
Thanks!

Answer 1

HEAD is the most effecient for existence checks:
HEAD /users/{username}
Request a user's path, and return a 200 if they exist, or a 404 if they don't.
Mind you, you probably don't want to be exposing endpoints that check email addresses. It opens a security and privacy hole. Usernames that are already publicly displayed around a site, like on reddit, could be ok.

Answer 2

I believe the proper way to just check for existence is to use a HEAD verb for whatever resource you would normally get with a GET request.
I recently came across a situation where I wanted to check the existence of a potentially large video file on the server. I didn't want the server to try and start streaming the bytes to any client so I implemented a HEAD response that just returned the headers that the client would receive when doing a GET request for that video.
You can check out the W3 specification here or read this blog post about practical uses of the HEAD verb.
I think this is awesome because you don't have to think about how to form your route any differently from a normal RESTful route in order to check for the existence of any resource, Whether that's a file or a typical resource, like a user or something.

Answer 3

GET /users?email=foo#bar.com
This is a basic search query: find me the users which have the email address specified. Respond with an empty collection if no users exist, or respond with the users which match the condition.

Answer 4

I prefer:
HEAD /users/email/foo#bar.com
Explanation: You are trying to find through all the users someone that are using the e-mail foo#bar.com. I'm assuming here that the e-mail is not the key of your resource and you would like to have some flexibility on your endpoint, because if you need another endpoint to check availability of another information from the user (like username, number, etc) , this approach can fit very well:
HEAD /users/email/foo#bar.com
HEAD /users/username/foobar
HEAD /users/number/56534324
As response, you only need to return 200 (exists, so it's not available) or 404 (not exists, so it's available) as http code response.
You can also use:
HEAD /emails/foo#bar.com
if the HEAD /users/email/foo#bar.com conflict with an existing rest resource, like a GET /users/email/foo#bar.com with a different business rule. As described on Mozilla's documentation:
The HEAD method asks for a response identical to that of a GET request, but without the response body.*.
So, have a GET and HEAD with different rules is not good.
A HEAD /users/foo#bar.com is a good option too if the e-mail is the "key" of the users, because you (probably) have a GET /users/foo#bar.com.