Proper HTTP method for updating resource without affecting sub-resources in REST

Question

Let's assume I have two entities - project team and employee. Each employee could be part of multiple teams and each team can have multiple employees as team members. I need to provide REST API to manipulate teams, employees and relationships between them.

I have identified 3 resources - team, employee and member (association between team and employee), which is sub-resource of team. The reason I chosen to have member as sub-resource is purely based on lifecycle of this resource. Whenever team is removed members are removed as well as they don't have meaning outside of team itself.

I expose following API (relevant ones):

• POST /teams creates new team record with name, department ID, etc.
• POST /teams/{name}/members creates association between team identified by name and particular employee, so the input data contains employee ID

I also need to provide API to update department ID and other attributes of the team in one request. Looks like PUT is natural choice but semantics of PUT is pretty clear - I have to replace whole resource, which in this case means replacing all members sub-resources as well.

What method (or approach) should I use when I only want to update team's attributes while preserving member associations? Please keep in mind that I also want this request to be idempotent.

Answer 1

Looks like PUT is natural choice but semantics of PUT is pretty clear - I have to replace whole resource, which in this case means replacing all members sub-resources as well.

I have never heard anyone make this association before. If do PUT /Foo in my opinion it says absolutely nothing about /Foo/bar. Just because resource can be accessed through a hierarchal URI space does not infer any additional relations between those resources.

I have heard of people doing the opposite scenario where you do PUT /Foo/bar and if the server knows that this will impact the state of /Foo you can include a Content-Location header that points to /Foo to allow intelligent caches to invalidate /Foo. However, the Content-Location is needed to explicitly create the relationship between the two resources.

Answer 2

Ideally, you should be using the PATCH method, but not sure which implementation uses it. If not, you should go the straight GET -> locally modify -> PUT cycle.

Also, depending on your design, you may interpret that sub-resources are not part of the resource itself. For instance, the contents of a team resource may contain a link to the list of resource members, say "/team/{name}/members", but not having the whole list as a contained element.