This morning I watched a great video by Bret Victor about the future of programming, told from the perspective of a computer scientist in 1973. One thing that really stuck with me was this line:
The most dangerous thought you can have as a creative person is to think you know what you are doing
Thinking we know what we are doing is pretty much the default for many of us. What we don’t realize about that line is how much work it is to really question things.
As an example, this morning we were adding the ability for users of a service to be able to reset their passwords. Let’s pretend for a moment that you were going to do that. What would you call the service? The URL?
Would it be
/passwords/forgot_password? If you’ve built systems before, those come to mind, because they are familiar. We know them. They slide right in. But they are *wrong*.
In a RESTful system, there are several guiding principles to naming, which include:
- Identification of resources
- Manipulation of resources through these representations
- Self-descriptive messages
If you’ve ever forgotten your password, you know that you don’t just say, “Oh I forgot my password” and have the system let you set a new one. In general, you need to prove your identity in some way. Which is the case here – we accept the request, and send a password to the user’s email. They have to click on that link to be able to verify that they have access to that email, and then they can reset their password. Let’s go back to the principles from above:
- Identification of resources – Our resource here is passwords. It may be accounts, or users, as well, but the primary thing we are acting on is a password
- Manipulation of resources through these representations – The manipulation in this case is to request a password reset email.
- Self-descriptive messages – We should be able to read the URI and it make clear what is going on.
All that said, we don’t end up with
/forgot_password or even
/passwords/forgot_password even though it was close. We instead end up with something like
GET /passwords/reset_request_form and
POST /passwords/reset_request_email. The latter because
POST implies a creation of a resource.
What I found interesting was that to come to this, I had to really challenge my initial assumption to just put
/forgot_password. It was such an unconscious decision to put it in there that it highlight just how much work it is to step back and figure out if you are doing something because it is the right thing, or because dogma has said this is what you do.
I’d highly recommend watching the entire video. It’s well worth your time, and may just help you be a better programmer, architect or designer.