RESTful reset password and confirm email

Question

im thinking what is the best RESTful way how confirm email and request reseting password. Im only aiming to find correct URI...

confirm email

PUT /users/{userId}/confirmEmail?code=xyz - does not seem much RESTful because of confirmEmail

PUT /users/{userId}/email?confirmedBy=xyz - maybe better? dunno

reset password (similar problem)

PUT /users/{userId}/resetPassword --DATA {email:[e-mail]} - same thinkin as before

PUT /users/{userId}/password --DATA {state:reseted,resent:[e-mail]} - hmmm... again Im not sure

are there any better ways in your mind?:-)

Answer 1

Firstly, I don't think that PUT is the right method for this. PUT broadly means "put this here", where the URL is identifying where the content should be located. You're really asking an existing resource to perform some action, which makes POST more correct.

To answer your direct question, a RESTful URL should identify the resource you want to handle your request. In this case, the resource is either the user, or some password-resetting resource within the user.

My preference would be for a password-resetting resource:

POST /users/{userid}/password-reset

This makes sense from a HTTP point of view, since you could issue a GET on the resource and receive something which indicates how to action a password reset (e.g. a HTML form prompting for the email address of the associated account).

EDIT:

For the purposes of email validation, there are two obvious options. You could either POST to a "confirm email" resource with the email address and confirmation data, to ask the server to process the confirmation, or you can execute a PUT to put the confirmation information on the server:

POST /users/{userid}/confirm-email

or

PUT /users/{userid}/email-confirmation

Answer 2

Considering that he said a reset service for someone who forgot her password, and not a change password service for someone already logged in...

I would use 2 services. 1st to request the reset password mail, and 2nd to set the new password with the token received in the received mail.

For the 1st:
POST baseUrl/passwordReset
Request body

{
   "email" : "[e-mail]"
}

This could be POST or PUT, but since a mail delivery is not a resource subject to CRUD anyway, let's not be pedantic and use the old POST that was always used in html forms.

Obviously I would control that the same client (ip? browser? ...) doesn't make me send 20K mails in a minute.

Sending the mail to the user doesn't imply that the old password is not valid. That will only happen later in the second request when the new one updates it.

Response 204 (perhaps you should do it even if you don't know that email, because if you return error that means that when you don't return error you are confirming to a stranger that the given email is registered)

For the 2nd:
POST baseUrl/password
Request body

{
    "token" : "3D21BA...4F",
    "newPassword" : "m%4pW1!O"
}

Where the token is received in the mail. So the mail could have a link to a page including the token, when the page is loaded, the form is filled and submitted, being the token a hidden field that some javascript reads from the URL and puts here.

This is really a resource that you update, so POST. And I don't think it makes sense to have the same URI with 2 verbs for both, because they are not the same resource/entity at all.

Add By the way, I would make both HTTPS only, and that's why I put all the sensitive information in the body, not URL parameters.

Answer 3

I don't really see anything wrong with having confirmEmail like the 1st example. In the URL you have the key to the user, confirmEmail is the action, and the data with that action is in the query string.

Answer 4

Here is a RESTful way.

Request

PUT /{userid}/email HTTP/1.1
Content-Type: text/json+confirmation-code

{"activateCode": "23sfgsg3twt3rgsdhgs"}

Response

HTTP/1.1 200 OK
Content-Type: text/json+email-status
{"email": "[e-mail]", "active": "true"}

No verbs in the URI needed :)

Answer 5

The true RESTful answer is the URL does not matter, you put it in the confirmation e-mail anyway for the recipient to follow. Use whatever is most convenient for your load balancer, reverse proxy, servers, etc.

For convenience you'll end up accepting the confirmation even if it comes in a GET request, because that's what the browsers of flesh-and-bones humans oblivious to Dr Roy T. Fielding et al. send when clicking on a link in an e-mail :-)

Having established it is completely academic, I'd argue you were right to think of PUT, as the client idempotently places evidence of having access to the e-mail. Repeating the request has no further effect.

Answer 6

If you want your URIs to refer to resources, then call the resource confirmation and POST confirmations to user accounts.

POST /users/{userid}/confirmation