I am developing a RESTful API in my project, but I do not have experience on that. To fill these gaps I've been watching some videos, mainly from Apigee, which are great. One situation brings a lot of discussion on my project and I hope you can help me clear it out. The client using the API is able to create a user by posting to my /Users url, but it has some requirements as: name format, username availability, email availability, valid region and many others. I can easily validate the name format in my client app, that would be easy. The problem is when it comes to availability (mainly if the email and the user name are available to be user or are already taken). We have two different lines of thoughts on my team:

the first one would break each verification in a different url, something like /Users/EmailAvailable and /Users/UsernameAvailable ou /Available/Email and /Available/Username

They claim that it would make the interface cleaner (more intuitive) and would also keep cohesion, since one method has only one responsibility.

The second line of thought is to have only one URL /User/Verify and it will verify either the username, email or both, depending on the JSON it receives. They claim that it would only require one trip to the server and that cohesion is not a problem because, since the URLs are not necessarily mapped to methods, they can divide the calls into methods that do one thing each. They also claim that the interface shouldn't care about cohesion

My questions: 1- Are these arguments about cohesion from the second line of though valid? 2- How would you do? (Either one of those or any other that you know of)


  • that is a great catch! Thanks! How would you check if the email inserted by the user is already taken? (we can't accept two or more users with the same email in our system)
    – JSBach
    Dec 4 '13 at 1:30
  1. You can't validate and create something atomically with several Rest Api requests. But if you must really do it, a HEAD request to /users/?[email=user@example.com|user=aUsername] should return 404 if it's not already exists. That way you don't put adjective (available) or verb (verify) in the Url. Keep it simple.
  2. I would POST User to /users and if username or email had been used, return 409 (conflict) with explanation either username or email is already exists.
  • No, I would like to provide a way to verify the availability of the email without creating the user. Creating the user is an independent call and not necessarily atomic. I just would like to know the best practice in providing this kind of method
    – JSBach
    Dec 4 '13 at 11:53
  • 1
    @Oscar Since you mentioned Rest and you want to check email/username in /users then that's how I'd do it. I just edited to change GET with HEAD request because you only want to know if the email/username exists or not, only need to check status code.
    – imel96
    Dec 4 '13 at 15:37

Unless you can those REST methods independently in other parts of the system, I would have the one REST endpoint which accepts a JSON payload containing all the data...two fields in this case. Of course you would refactor this out on the backend should you need to open up a second endpoint which will allow you to check separately. One connection also works nicely for mobile devices.

If you plan on checking for the availability of e-mails, ensure you use a captcha verification image. Depending on your budget and your UX requirements, you might want to introduce captcha only if more than n number of e-mail checks are done within a certain time frame.

Captcha is faily easy to integrate. There are a few providers out there, but the most popular one seems to be https://www.google.com/recaptcha/captcha

  • We are creating the API that is meant to be open to the public, so we do not know how it is going to be used. would you have any reason why the only one endpoint?
    – JSBach
    Dec 4 '13 at 11:56
  • 1
    If you think about it, If an e-mail address is unavailable, it means it's in use. If it's in use, why would you need to check for the availability of the username? The two are tied together. If a username is taken, it's tied to an e-mail address. A modern approach is to use the email as the username.
    – Razor
    Dec 4 '13 at 22:40
  • Yes, that is true, but we have the email, which is used to login and a username is used to the user's open open (just like facebook, your profile page is /username). I would like to be able to check both individually, only the email or only the displayname. This can still be achieved with one method only, but it looks confusing to me
    – JSBach
    Dec 5 '13 at 12:46

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.