As part of our project (web application), we have to design REST API to manage the users of our application. Our API will be based on a company user management product (I will call it: C.U.M.) that manages all users of all company applications (for each application we have a specific group).

So by definition: a user of our application necessarily exists in C.U.M. under a very specific group, with other information in its own DB(as the birth date for example).

In order to create a user for our application, you have to go through several steps. during the first step, the user enter his: first name, last name, birthdate and email.

Before being able to proceed to the next step, you must do the following checks based on the email address as a research criterion:

case 1: user doesn't exist in C.U.M. ==> Ok => step 2

case 2: a user exists in C.U.M. for another application (different group) ==> error message 1

case 3: a user of our application exists in C.U.M.(our application group) with different information (first name, last name, birth date) ==> error message 2

case 4: a user of our application exists in C.U.M.(our application group) with the same information (first name, last name, birth date) ==> go to user modification step

How can we design my RESTful API to handle these cases? can I use the options verb by exploiting the body to handle these different cases, otherwise how can I choose my uri in this case?

I thought of this solution: create an email search uri (GET /users?email="zzzz") and do the necessary checks on the front side. But, the problem in this case, that I will not be able to tell the difference between case 1 and case 2. Since in both cases I am not supposed to find any user...

  • you're going to have to do the check on the backend too, if for no other reason than to avoid the race condition of the same person getting added by 2 people. Besides, REST APIs don't inherently have a front side. What if I call the api directly?
    – erik258
    Nov 1, 2020 at 17:38
  • worst name evar
    – Ewan
    Nov 1, 2020 at 22:30
  • @DanielFarrell The problem that we have to go through our API since we are going to manage other properties for our user which will be inserted in our database. Otherwise I agree, that we must use the same validation on the backend side when finalizing the creation of the user. The need at the moment is to block the user from going to the next step if the basic information is wrong.
    – Omar ZRIDI
    Nov 1, 2020 at 23:37
  • @Ewan I truly thank you for taking the time that you did to give me answers. it's very constructive :)
    – Omar ZRIDI
    Nov 1, 2020 at 23:56

2 Answers 2


POST /api/users seems to be sufficient. Either way you have to run validation on the server side. So you can return 400 Bad Request whenever you found something wrong with input or it didn't pass business-logic validation. Otherwise, you would return 201 Created with header Location <new user id> such that consumers of your API could know the ID of newly created user.

It's pretty standard way to go.

Regarding your comment.

It makes little to no sense to validate on the first step and proceed to next steps after. Why? At least because it is not secure, not at all. There is no way you can trust your clients, even if they come from the internal private space your organization has control over. Which implies: any way - no matter what was done a priori - you gonna repeat all the actions taken at the last step on the server side. So don't make your life harder, just run simple validation right in browser and accumulate data up to the moment when it's all ready and can be POSTed to the /api/users endpoint.

Note that GET /api/users?email= can be used to check that given account already exists or not.

  • It would be a good solution if we didn't have further steps to finish to create the user. In fact, the objective of the first step is just to validate the basic information of the user before moving on to the next step.
    – Omar ZRIDI
    Nov 1, 2020 at 23:37
  • @OmarZRIDI see my update.
    – Zazaeil
    Nov 2, 2020 at 12:26
  • Knowing that we have planned to make the same validations on the backend side in the last step when we are going to submit user information, can we consider our API to be secure? Otherwise, I agree that th checks are complicated but unfortunately it is the functional need. What we suggested as the dev team to do the checks: case 1, case 3 and case 4 in the first step using the research by email. and for case 2, return 400 Bad Request during the last step.
    – Omar ZRIDI
    Nov 2, 2020 at 22:21

If I understand correctly, I find your solution a bit too complex. First you should break each case into a specific API call. Then, for every API call you can return a certain HTTP status code so that your client knows how to graciously handle each case.

For example, suppose you are in the first case where you try to insert a new user to your system and the user does not yet exist. You then should return the HTTP status for that situation so that the client knows that it has to proceed to the next API call(check if the user exists in some other application). The other cases are similar and should all be handled by the client by leveraging the HTTP status code returned each time.

  • 1
    In fact, behind each http code a very specific signification.So, I think it's not a good idea to manage a status for each case.
    – Omar ZRIDI
    Nov 1, 2020 at 23:38

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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