REST API design: POST (implicit userId) vs PUT (explicit userId)

Question

For some routes on an API, like GET /news, one would asume the user only wants news that pertains to them, so the userId is implicitly taken from authentication info.

However, some of the routes on an API i'm designing modify the "users" resource - i.e. changing some account info. For example, the user might want to change their name on the account. I could do

POST /users/name

or

PUT /users/:userId/name

1) Is this dichotomy generally correct (correct meaning most REST APIs would be designed in this fashion)? The idea that PUT would use an explicit userId where POST would take it from authentication info

2) If yes to the above, which style makes more sense for "modifying-account-info" type routes? If no, what do you suggest?

Answer 1

I've seen good APIs designed both ways. On the one hand, providing the userId in authentication and the URL seems redundant.

On the other hand, it could be more consistent to have an explicit Id in the URL if there are also ways for one user to look at public data of another user or you are using the same or a similar API in clients that need to get data for many users. That way, you always provide a userId in the URL, no matter if it's redundant or not.

As an aside, I have also seen APIs where you could use the word "me" in the URL to refer to the authenticated user.

Answer 2

There are basically two different questions in one. Let me simplify and rephrase them:

1. If you have userId once as authentication info and once as a part of a data object which one should win?

None of them should win. These are two different userIds one is user performing the action another is the data object user as a subject of the action. Think of admin renaming another user. in case of a normal user you should compare this two id-s and return some error status code if they differ.

2. How to design an API call to the resource location which modifies the location itself? Example: PUT to /users/{name} would potentially alter the name.

That's why you have userId. I assume userId do not change. So use this location to PUT to to update the user. As a convenience you can provide response redirect on the location /users/{name} to corresponding permanent location of the resource.

Answer 3

Your GET /news essentially hides with what resources are you working with behind authentication info (which is usually transferred to the server using sessionId). This isn't RESTful, as you should explicitly define what resources are you working with in the URL.

Correct version is:

GET /news?userId=:userId

Even in this case you use the authentication info to validate/authorize the request, but this is OK from the REST point of view.

The only exception to this rule is the POST when you're creating a new entity while the key is generated on the server - in this case you omit the ID because you don't know it yet. It has some disadvantages (non-idempotent), using PUT with client-generated key is better.