How to design my REST API

Question

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...

Answer 1

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.

Answer 2

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.