Consider a web page where a user changes his password after clicking on an emailed password reset link.
The page will be implemented against an API using ajax, rather than as an ordinary form submission. That is, this question is about designing an API endpoint for changing a password.
Requirements
Any time a password is changed, the change must be recorded in the database in the password_changes
table:
password_changes
- user_id
- date_changed
Specific Question
Thinking about this design from the perspective of API endpoints that create, update, or delete abstract "resources", does it make more sense to think about the password change as:
We're updating the "user" resource, and hence should
PUT
a new password onto/user/{id}
or perhaps/user/{id}/password
? In this model, recording the change inpassword_changes
is just an irrelevant implementation detail, and has no bearing on our concept of the "user" resource or the name of our endpoint.We're creating a "password_change". Thus we should be
POST
to/user/{id}/password_change
, or something similar. In this model, the change to the "user" resource is just a side effect of creating a "password_change".
In this particular example, I think most people would choose option 1. And indeed it feels more natural to me too. Buy why? Is this just a matter of judgment, taste, or intuition? Or is there some codified principle of REST or even the basic concepts of resources and http actions that option 2. clearly violates?
(EDIT 3/2/2019: Fwiw, #2 now seems much more natural to me, and I'm confused why my former self felt #1 was more natural)
More General Question
What if we provide a history of password changes as a new enpoint: /user/{id}/password_changes
?
That seems like a reasonable service.
But if we stick with design 1., now we make password changes by making PUT
s to /user
but view them with GET
s to /user/{id}/password_changes
. And then do we just disallow other http actions to password_changes
(PUT, POST, DELETE)? That seems inconsistent... or maybe not?
Again, what are the rules (or even heuristics) governing these decisions? I can make judgment calls, but I'm looking for something more definitive.