REST API Endpoint for changing email with multi-step procedure and changing password

Question

I need help for creating the REST endpoints. There are couple of activities :

To change the email there are 3 URL requests required:

1. /changeemail : Here one time password (OTP) is sent to the user's mobile

2. /users/email : the user sends the one time password from previous step and system sends the email to the new user to click on the email activate link

3. /activateemail : user clicks on the link in the new email inbox and server updates the new email

To change password :

1. /users/password (PATCH) : user submits old password and new password and system accordingly updates the new password

Similarly, there are other endpoints to change profile (field include bday, firstname and last name)

after reading online I believe my system as only users as the resource --> so to update the attributes I was thinking of using a single PATCH for change email and change password and along with that something like operation field so the above two features will look like :

For changing email :

1. operation : 'sendOTPForEmailChange'
2. operation : 'sendEmailActivationLink'
3. operation : 'activateEmail'

For changing password :

1. operation : 'changePassword'

and I will have only one endpoint for all the above operations that is (in nodejs) :

app.patch('/users', function (req, res) {
  // depending upon the operation I delegate it to the respective method
   if (req.body.operation === 'sendOTPForEmailChange') {
       callMethodA();
   } else if (req.body.operation === 'sendEmailActivationLink') {
     callMethodB();
   } else if (req.body.operation === 'activateEmail') {
      callMethodC();
   } else if (req.body.operation === 'changePassword') {
      callMethodC();
   } else sendReplyError();

});

Does this sound a good idea ? If not, someone can help me form the endpoints for changeemail and changepassword.

Answer :

I finally settled for using PATCH with operation field in the HTTP Request Body to indicate what operation has to be performed. Since I was only modifying a single field of the resource I used the PATCH method. Also, I wanted to avoid using Verbs in the URI so using 'operation' field looked better.

Some references I used in making this decision :

Wilts answer link here

Mark Nottingham' blog link article

and finally JSON MERGE PATCH link RFC

Answer 1

You should make the links that define the particular resource, avoid using PATCH and adding all the logic in one link keep things simple and use separation of concern in the API like this

1- /users/otp with HTTP Verb: GET -> to get OTP for any perpose
2- /users/password/otp with HTTP Verb: POST -> to verify OTP for password and sending link via email
3- /users/activate with HTTP Verb: POST to activate the user
4- /users/password with HTTP Verb: PUT to update users password

Answer 2

Hashing Security is a must read, IMHO, should you ever want to implement your own user account system.
Two-factor identification should always be considered, at least as an opt-in feature. How would you integrate it into your login scheme ?
What about identity federation ? Can your user leverage their social accounts to use your app ?

A quick look at Google yielded this and this, as well as this.

Unless you have an excellent reason to do it yourself, I'd spend time integrating a solution that is backed by a strong community for the utility aspects of the project, and focus my time on implementing the business value for your customers.

NB: my text was too long for the comments

Answer 3

Mostly agree with Ghulam's reply, separation of concerns is key. I suggest slightly different endpoints as following:

1. POST /users/otp      -> as we are creating a new OTP which should be returned with 200 response. 
2. POST /users/email    -> to link new email, request to include OTP for verification. 
3. PUT  /users/email    -> to activate the email.
4. PUT  /users/password -> to update users password.