A managing resource controls which subordinate resources are added to or removed from a directed relationship. In an API, attach the add and remove methods to the managing resource, while passing the subordinate resource's identifier. section 15.2 section 15.3
Choose this pattern deliberately:
- Select exactly one managing resource, even when either direction seems reasonable; the relationship is intentionally nonreciprocal. section 15.2 section 15.4.1
- Name methods Add<Managing-Resource><Associated-Resource> and Remove<Managing-Resource><Associated-Resource>. section 15.3
- Send the managing resource as the parent and the subordinate resource as an identifier, rather than embedding the full subordinate resource. section 15.3
- Prefer this approach when the relationship needs no metadata such as membership dates or roles; use an association resource when that information matters. section 15.2 section 15.6
Groups managing users
If groups manage user membership, expose AddGroupUser and RemoveGroupUser. Adding user 1 uses AddGroupUser({ parent: "groups/1", userId: "users/1" }) or POST /groups/1/users:add with { userId: "users/1" }; removal follows the corresponding :remove method. section 15.3
Listing 15.1 Code snippets for two alternatives when choosing a managing resource
group.addUser(userId); #1 user.addGroup(groupId); #2
Compare the two possible directions directly: group.addUser(userId) makes the group managing, while user.addGroup(groupId) makes the user managing. section 15.2
