I want to provide the ability for resetting a user`s password. This call obviously must not require authentification. First I thought of something like this:
DELETE /users/{id}/password: generates a reset token that gets sent to the user via email
POST /users/{id}/password: requires the new password and a valid reset token in the body
But the problem is, the application or website cannot provide me the ID of the user, because all it can ask the user for is his email address.
There are a number of other (unauthenticated) calls to our API, where the ID is not present and the user is only identified by its email.
We discussed the following solutions in our team:
If I had to choose between those two, I would take the first one, because I think it is not RESTful to provide something essential with query parameters, as they always represent something optional, like filtering a resource. Are there better ways to design these URLs or is replacing the ID with the users email just fine concerning REST contraints?
POST /passwordResets
{
"emailAddress": "bob@example.com"
}
Then you have the flexibility to reset by userId also, and you can track the resets just like any other resource for auditing purposes.
Of your two options, the first isn't awful if you can use an email address to uniquely identify a user. It's conceptually wrong, though, because there should be one canonical location for each resource, and now you have two - /users/bob/password and /users/bob@example.com/password.
The second option is just wrong. /users/password is not meaningful. The direct implication of /users is that the next path element is a user. /users/password is closer to RPC than REST.