Intent

Currently, the spec defines ways to

1. replace the whole value of a to-many relationship while updating the base resource (PATCH /users/5);
2. add some elements to a single to-many relationship at a time (POST /users/5/relationships/posts);
3. remove some elements from a single to-many relationship at a time (DELETE /users/5/relationships/posts).

This proposition defines a backwards compatible way to enrich 1. so that a single request can simultaneously update the attributes of a resource, add some elements to some of its to-many relationships, remove elements from some of its to-many relationships, and fully replace some of its to-many relationships.

This proposal is solely about relationships, and does not tackle the issue of creating/deleting/modifying related resources along an update (unlike for instance discussed in #795, #1089), but only the relationship itself.

Proposal

Updating a Resource’s Relationships:

If a relationship is provided in the relationships member of a resource object
in a PATCH request, its value MUST be a relationship object with a data member.

The relationship’s value will be replaced with the value specified in this member.

becomes (up to wording)

Updating a Resource’s Relationships:

If a relationship is provided in the relationships member of a resource object
in a PATCH request, its value MUST be a relationship object with **either** a
data member **or one or both of an added-data member, and a removed-data member**.

**In case a data member is specified, the relationship’s value will be replaced**
**with the value specified in this member.**

**In case an added-data member is specified, the values specified in this member**
**will be added to the relationships’s value. (Note: This should not raise an**
**error if part of the edges already exist).**

**In case a removed-data member is specified, the values specified in this member**
**will be removed from the relationship’s value. (Note: This should not raise an**
**error if part of the edges do not exist).**

such that the following request:

// PATCH http://api.example.com/posts/5
{
  "data": {
    "type": "posts",
    "id": "5",
    "attributes": {
      "title": "Cool updated title",
    },
    "relationships": {
      "tags": {
        "added-data": [
          { "type": "tags", "id": "4" }
        ],
        "removed-data": [
          { "type": "tags", "id": "2" }
        ]
      },
      "comments": {
        "removed-data": [
          { "type": "posts", "id": "5" }
        ]
      },
      "images": {
        "data": [ 
          { "type": "image", "id": "7" }
        ]
      }
    }
  }
}

would be valid, and would have as effects:

• modify the attribute title of the post;
• add an (existing) tag to the post;
• remove a tag from the post;
• remove a comment from the post;
• replace the set of images attached to the post.

whereas currently, it would take 4 requests to accomplish that:

1. modify the title attribute and replace the images relationship;
2. add an existing tag to the post;
3. remove a tag from the post;
4. remove a comment from the post.

Pros

1. Lifts the burden of "full-replacement or multiple requests" when updating to-many relationships;
2. backwards compatible.

Cons

1. Introduce some asymmetry between documents sent and received by the server (although such asymmetry already exists, as for instance included can only be present in a response)

More context: see this blog post.