How to create/update many-to-many relationships in a RESTful API

Question

This is how you add a player to a team in my API:

PUT /teams/1/players/1/

I now want to change the player to another team.

How can I do that?

Answer 1

Changing a resource is usually done via HTTP PUT or HTTP PATCH (the latter one if only a partial update should be executed). However, using a construct like PUT /teams/1/players/1?moveToTeam=2 has some semantic issues of replacing the current representation with the payload found within the body of the request. The optional query parameter is a method you invoke on the server side to move a player from team 1 to team 2. However, HTTP PUT is an idempotent operation which basically means if you execute the same statement twice it will yield the same effect. Though, as you are removing the player from team 1 and copying the data of the current user to a new location, invoking the same method violates the idempotent nature of HTTP PUT as a consecutive call will either fail as no /teams/1/players/1 resource is available or no content for the player is available and therefore the content of the moved player will also get set to an empty body. Therefore I do not recommend using HTTP PUT.

Probably DELETE /teams/1/players/1?moveToTeam=2 is the closest single HTTP operation you can get to move a player from one team to another. This request successfully deletes the player from team 1 which should not be available after the invocation and therefore a further invocation wont change the resource (idempotent). The operation should return a 200 OK including the new state of the player entity which link should point now to its new location. HTTP DELETE also allows resources to be moved, according to the spec. Though, the spec states that this resource should not be accessible after the operation was executed.

The DELETE method requests that the origin server delete the resource identified by the Request-URI. This method MAY be overridden by human intervention (or other means) on the origin server. The client cannot be guaranteed that the operation has been carried out, even if the status code returned from the origin server indicates that the action has been completed successfully. However, the server SHOULD NOT indicate success unless, at the time the response is given, it intends to delete the resource or move it to an inaccessible location.

A successful response SHOULD be 200 (OK) if the response includes an entity describing the status, 202 (Accepted) if the action has not yet been enacted, or 204 (No Content) if the action has been enacted but the response does not include an entity. (Source)

Therefore this operation is a bit risky if you try to be fully RESTful IMO.

I therefore would recommend to split the operation into atomic units:

• Retrieve the current data of the user to move and store is temporarily (GET /teams/1/players/1)
• Remove the player from team 1 (DELETE /teams/1/players/1)
• Add the player to the team you want the player to belong to. Use the temporarily stored data as payload in the request (POST /teams/2/players)
• Create a redirect (301 Moved Permanently) for users who still have a reference to GET /teams/1/players/1 so that they automatically get forwarded to GET /teams/2/players/n where n is the new ID of the player.

Each operation obeys to the rules defined within the HTTP specification and therefore it should be fine separating the requests into atomic portions.

---

UPDATE

While I agree with @EricStein that separating players to their own resource, as this simplifies a move of a player from team1 to team2 drastically, I had a look at the PATCH method also and it seems it is more appropriate than DELETE or splitting the move into multiple atomic requests.

PATCH is often confused with a partial update where just the new value for a resource-property is sent to the server, which it is not. The result of PATCH may be equal but PATCH sends necessary steps the server has to execute in order to transform a resource from one state to a new state. The spec clearly states:

The PATCH method requests that a set of changes described in the request entity be applied to the resource identified by the Request- URI. The set of changes is represented in a format called a "patch document" identified by a media type. If the Request-URI does not point to an existing resource, the server MAY create a new resource, depending on the patch document type (whether it can logically modify a null resource) and permissions, etc.

The difference between the PUT and PATCH requests is reflected in the way the server processes the enclosed entity to modify the resource identified by the Request-URI. In a PUT request, the enclosed entity is considered to be a modified version of the resource stored on the origin server, and the client is requesting that the stored version be replaced. With PATCH, however, the enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version. The PATCH method affects the resource identified by the Request-URI, and it also MAY have side effects on other resources; i.e., new resources may be created, or existing ones modified, by the application of a PATCH. (Source)

Especially the last quoted line states that it can have side-effects and may create new resources. Therefore, if you can't change your model for whatever reason, PATCH is probably the best way to move a player from one team to an other. This method allows you to send the necessary steps the server has to execute in order to create the new resource for the moved player, delete the old representation and establish a permanent forward to the new resource in one single request. However, this operation is neither safe nor idempotent!

Answer 2

What about doing something like POST /teams/1/players/5/transfers. This would have the effect of creating a "Team Player Transfer". The id of the Team and the Player are provided in the url, and the body can be something like { new_team_id: 2 }. The server can then perform the "transfer" however it likes.

The "Transfer" may or may not be an object in the database (in my situation it is not). This structure seems RESTful to me and it also reads intuitively.

Answer 3

Can I respectfully suggest not doing this? Instead, make /players and /teams both top-level resources. Control what team a player is on using a property on the player. Then you can update a player's team by PUTting the player with the new team value.

Alternately, make a new top-level resource that contains all the player-team mappings, say '/team-memberships'. Then you could query GET /team-memberships?teamId=7 or GET /team-memberships?playerId=2. You can post and delete to this resources to add and remove players from teams.

Conceptually, a player is not a sub-resource of a team. A player is an independent resource that's associated with a team. I think either of the above approaches will give you more flexibility and be easier to understand and work with.