What's the REST way to verify an email?

Question

When a user register to my web application I send an email to verify his inbox. In the email there are a link to a resource like this:

GET /verify/{token}


        

Answer 1

Aren't you overthinking REST? With e-mail verification you want the user to be able to simply click the link from whatever mail user agent he is using, so you'll end up with a simple GET on the server (presented as a hyperlink to the user) with the token either in the path or as part of the query string:

GET http://example.com/verify-email/TOKEN
GET http://example.com/verify-email?token=TOKEN

Either is fine for this use case. It is not really a resource you are getting or creating; just a trigger for some process on the backend.

Why do you think this would run afoul of good design?

Answer 2

It depends on what are you trying to do.

Does it fire an email after validating the user for example? If so, it is not an idempotent method and you should use POST.

Example:

POST /users/{id}/verify/{token}

If the method doesn't have any consequence besides the update, I think you should use PUT.

Answer 3

What you are talking about is not REST. REST is for machine to machine communication and not for human to machine communication. You can develop a 1st party REST client, which sends the activation to the REST service.

You can use your verification URI in the browser to access the REST client:

# user follows a hyperlink in the browser manually

GET example.com/client/v1/verify/{token}
# asking the client to verify the token

and after that the REST client will get the hyperlink for verification from the REST service and send the POST to the service in the background.

# the REST client follows the hyperlinks given by the service automatically
# the REST client can run either on the HTTP client or server side

GET example.com/api/v1
# getting the starting page of the REST service
# getting the hyperlink for verification

POST example.com/api/v1/verification {token}
# following the verification hyperlink

If you have a server side 1st party REST client, then the HTTP requests to the REST service will run completely on the server and you won't see anything about it in the browser. If you have a client side REST client, then you can send the POST in the browser with AJAX CORS or you can try to POST directly with a HTML form (not recommended). Anyways the activation should be a POST or a PUT.