2

Let's say we have two kinds of resources, user and group.
Every user can belong to multiple groups and each group can have many members.
Thus I can model my API like this 

/
|_ /users/{id} 
|   |_ groups
|
|_ /groups/{id} 
    |_ members

Let's say our resources exposes only two actions. You could either add a user to a group or remove one from it.
When it comes to the implementation I could think of two possible requests for each action.
You could PUT a new user in a group's members collection, or PUT a new group in a user's groups collection.

Should I implement both "entry points"? Is this expected in RESTful applications? If not, which one should I implement?

Improve this question
1
  • Keep this in mind YAGNI.
    – Laiv
    Commented Nov 7, 2016 at 19:51

2 Answers 2

Reset to default
6

REST doesn't have any expectations on this. You can implement both or only one of them. Also there is a possible third options to have a resource user_group_relation which handles this functionality.

Which one you need or want to implement depends on your needs. If it's for a pure API one should be enough (I would go for adding a member to a group, since this feels more natural).

But if you have a web site or app that offers both options for editing and has two very distinct types of response it may be more comfortable to implement both. Say a user page has a list of groups where you can add groups and at the same time your groups show lists of users where you can add new members. Both lists are very different, both actions would have to return very different responses to update those lists (and maybe more info specific to those pages like number of groups for the user, number of users for the group).

Improve this answer
2
  • Thank you for the answer! What is a PUT/POST response expected to show? I know that a POST response should point to the URL of the resource created, but shouldn't every other data be retrieved by GET requests? I'm assuming a strong separation between client functionalities and server resources model. My API shouldn't serve a specific implementation of the client, but be open to other possible clients. I believe this is great for extensibility and maintenance.
    – seldon
    Commented Oct 24, 2014 at 9:38
  • @mattecapu One additional thing which might give some useful context is the chapter about Compound Documents in the JSON API "standard": jsonapi.org
    – Muton
    Commented Oct 24, 2014 at 9:41
2

I'd recommend using only one method of adding/removing users in groups. To keep it simple, in a well design API there should be only one path to achieve each action. Moreover, that path should be the shortest possible.

Now to choose what is the right path (PUT /users/{idu}/groups/{idg} or PUT /groups/{idg}/users/{idu}). It's up to you, but I'd rather use the second one. Because it's the answer of who owns who ? Or What is composed of what ?

It is not a dogmatic answer, there could be reasons to choose the first one especially if you you consider the fact that being in group is property of the user.

Improve this answer
3
  • Thank you for the answer! The simplicity argument is good, yet I'm not totally convinced. As in my example, cases without any clear preference over the two methods can be common. If behind my API I have a routing system, attaching the same code to both the URLs will be easy, and then we provide the user with a complete API.
    – seldon
    Commented Oct 24, 2014 at 9:45
  • 1
    @mattecapu, as I said before, this is not a dogmatic answer, both ways can be considered right. And I was not considering the implementation that is not, as you said it, more complicated when choosing the 2-paths approach. To add further arguments, one can also consider HTTP caching mechanisms : If you want to cache your GET requests, you must invalidate simultaneously your 2 path options whereas using the single path approach make it more simple.
    – superbob
    Commented Oct 24, 2014 at 11:40
  • Cache invalidation could be an issue, actually. But thinking about it, the two entry points doesn't return the same resource, and the cache would be invalidated anyway with a single path. Moreover, I expect the API clients to be consistent with the path used. This could be pinpointed in the documentation.
    – seldon
    Commented Oct 24, 2014 at 11:59

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.