REST API design for resource modification: catch all POST vs multiple endpoints

Question

I'm trying to figure out best or common practices for API design. My concern is basically this:

PUT /users/:id 

In my view this endpoint could by used for a wide array of functions. I would use it to change the user name or profile, but what about ex, resetting a password?

From a "model" point of view, that could be flag, a property of the user, so it would "work" to send a modification.

But I would expect more something like

POST /users/:id/reset_password

But that means that almost for each modification I could create a different endpoint according to the meaning of the modification, i.e

POST /users/:id/enable
POST /users/:id/birthday
...

or even

GET /user/:id/birthday

compared to simply

GET /users/:id 

So basically I don't understand when to stop using a single POST/GET and creating instead different endpoints.

It looks to me as a simple matter of choice, I just want to know if there is some standard way of doing this or some guideline. After reading and looking at example I'm still not really sure.

Answer 1

Disclaimer: In a lot of cases, people ask about REST when what they really want is an HTTP compliant RPC design with pretty URLs. In what follows, I'm answering about REST.

In my view this endpoint could by used for a wide array of functions. I would use it to change the user name or profile, but what about ex, resetting a password?

Sure, why not?

I don't understand when to stop using a single POST/GET and creating instead different endpoints.

A really good starting point is Jim Webber's talk Domain Driven Design for RESTful systems.

First key idea - your resources are not your domain model entities. Your REST API is really a facade in front of your domain model, which supports the illusion that you are just a website.

So your resources are analogous to documents that represent information. The URI identifies the document.

Second key idea - that URI is used by clients to cache representations of the resource, so that we don't need to send requests back to the server all the time. Instead, we have built into HTTP a bunch of standard ways for communicating caching meta data from the server to the client.

Critical to that is the rule for cache invalidation: a successful unsafe request invalidates previously cached representations of the same resource (ie, the same URI).

So the general rule is, if the client is going to do something that will modify a resource they have already cached, then we want the modification request to go to that same URI.

Your REST API is a facade to make your domain model look like a web site. So if we think about how we might build a web site to do the same thing, it can give us insights to how we arrange our resources.

So to borrow your example, we might have a web page representation of the user. If we were going to allow the client to modify that page, then we might think through a bunch of use cases (enable, change birthday, change name, reset password). For each of these supported cases, we would have a link to a task-specific form. Each of those forms would have fields allowing the client to describe the change, and a url in the form action to decide where the form gets submitted.

Since what the client is trying to achieve is to modify the profile page itself, we would have each of those forms submit back to the profile page URI, so that the client would know to invalidate the previously cached representations if the request were successful.

So your resource identifiers might look like:

/users/:id 

/users/:id/forms/enable
/users/:id/forms/changeName
/users/:id/forms/changeBirthday
/users/:id/forms/resetPassword

Where each of the forms submits its information to /users/:id.

That does mean, in your implementation, you are probably going to end up with a lot of different requests routed to the same handler, and so you may need to disambiguate them there.