Imagine that I have a system to manage sports teams. Let's not make it specific to a particular sport, but consider that each team consists of a number of players.
Therefore, I might have an operation like this to add a player to a team.
POST http://.../teams/myteam/players/
And something like this to update a player's details.
PUT http://.../teams/myteam/players/foobob
And this to get a list of players in a team.
GET http://.../teams/myteam/players
Now, each player has a specific position within the team - and I have a user interface where someone can change the positions of those players within the team. So I might drag player #1 to position 4, player #2 to position 1, and player #3 to position 6. The impact of this change should only take effect once the user has completed the entire operation - so I cannot update individual players on the fly.
Consequently, at the end of this process, I have some kind of object that maintains an updated mapping of player to order - Player Name -> Number
. I now need to push these changes from the front-end to the back-end. However, given that I'm updating the team as a whole, what should my REST endpoint for this operation look like? I'm updating an entire collection of entities with a new ID, so it doesn't feel right to publish it to a player-specific endpoint. Hence, I think I should treat the team as the resource being updated.
I'm also wary of doing a PUT to the team, given that I'm modifying only a single field on each player, rather than replacing the 'team' entity in its entirety.
I'm leaning towards using PATCH to update the team, and then specifying the reordering as part of the body. This will then go off and update the individual players belonging to the team. Are there any obvious design issues with this?
PATCH http://.../teams/myteam
{
{player: bob, number: 1},
{player: foo, number: 3},
{player: bazbar, number: 2}
}