Should I specify the userId in the REST URL structure?

Question

Basically, one feature of my app is to retrieve the logged user's friends.

Actually, I hesitate between both kind of endpoints:

1. GET /api/users/friends
2. GET /api/users/:userId/friends

Using 1, userId would be reachable through the authentication token.
Using 2, server would have to additionally check for the correspondance between the passed userId, and the logged user id specified in the auth token so that it avoids any malicious access to other user data, like friends.

So 1 should be enough, but it doesn't sound like a standard rest url.

What is a good practice?

Answer 1

The first solution has a benefit of avoiding data duplication. The request plainly means:

Hello, I'm John. Give me the list of my friends.

If possible, I would even shorten it to GET /api/friends.

On the other hand, if you expect to be able to access friends of other users, the second solution appears the good one. The request means:

Hello, I'm John. Give me the list of friends of John.

but can also be:

Hello, I'm John. Give me the list of friends of Mary.

For instance, one situation where such change can be possible is where a person can find her own friends, but also friends of her friends.

• Mik378: Neat answer, thanks. You've just confirmed what I thought ;)
• ArTs: I would go a step further. With GET /api/friends I would rename it GET /api/myFriends. From a discoverability point of view its more self documenting. Further, with REST its useful to think about how a browser/proxy cache would handle it. With GET /api/myFriends it is entirely possible to have a bug where you display the wrong friends due to caching.
• Jbm: There is one catch when you use relative URIs (relative to the logged in user) certain scenarios become awkward to implement. Particularly when you want to let a user impersonate another, such as a support user that needs to login and see everything as another user. If he is logged in as the support user, but tries to impersonate a user he wants to help, he is going to end up looking at his own friends, not the user's he is trying to help.

Answer 2

Rest Api's must be hypertext driven ! As you would click from one link to another in a standard html page.

An URL is a unique identifier to a resource. Having an url representing more than one resource is in total disacordance with ReST.

With your example, the following url :

/api/users/:userId

should have a link in its response to the :userId friends url

Roy Fielding's dissertation contains a set of constraints needed to comply to ReST.

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://fr.slideshare.net/rnewton/2013-06q-connycrestfulwebapis http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm