{"action":"opened","issue":{"url":"https://api.github.com/repos/json-api/json-api/issues/1097","repository_url":"https://api.github.com/repos/json-api/json-api","labels_url":"https://api.github.com/repos/json-api/json-api/issues/1097/labels{/name}","comments_url":"https://api.github.com/repos/json-api/json-api/issues/1097/comments","events_url":"https://api.github.com/repos/json-api/json-api/issues/1097/events","html_url":"https://github.com/json-api/json-api/issues/1097","id":178040483,"number":1097,"title":"Proposal: updating multiple to-many relationships in one request","user":{"login":"beauby","id":2215778,"avatar_url":"https://avatars.githubusercontent.com/u/2215778?v=3","gravatar_id":"","url":"https://api.github.com/users/beauby","html_url":"https://github.com/beauby","followers_url":"https://api.github.com/users/beauby/followers","following_url":"https://api.github.com/users/beauby/following{/other_user}","gists_url":"https://api.github.com/users/beauby/gists{/gist_id}","starred_url":"https://api.github.com/users/beauby/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/beauby/subscriptions","organizations_url":"https://api.github.com/users/beauby/orgs","repos_url":"https://api.github.com/users/beauby/repos","events_url":"https://api.github.com/users/beauby/events{/privacy}","received_events_url":"https://api.github.com/users/beauby/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":0,"created_at":"2016-09-20T12:01:22Z","updated_at":"2016-09-20T12:01:22Z","closed_at":null,"body":"# Intent\r\nCurrently, the spec defines ways to\r\n1. replace the whole value of a to-many relationship while updating the base resource (`PATCH /users/5`);\r\n2. add some elements to a single to-many relationship at a time (`POST /users/5/relationships/posts`);\r\n3. remove some elements from a single to-many relationship at a time (`DELETE /users/5/relationships/posts`).\r\n\r\nThis 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. \r\n\r\nThis 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.\r\n\r\n# Proposal\r\n\r\n```\r\nUpdating a Resource’s Relationships:\r\n\r\nIf a relationship is provided in the relationships member of a resource object\r\nin a PATCH request, its value MUST be a relationship object with a data member.\r\n\r\nThe relationship’s value will be replaced with the value specified in this member.\r\n```\r\nbecomes (up to wording)\r\n```\r\nUpdating a Resource’s Relationships:\r\n\r\nIf a relationship is provided in the relationships member of a resource object\r\nin a PATCH request, its value MUST be a relationship object with **either** a\r\ndata member **or one or both of an added_data member, and a removed_data member**.\r\n\r\n**In case a data member is specified, the relationship’s value will be replaced**\r\n**with the value specified in this member.**\r\n\r\n**In case an added_data member is specified, the values specified in this member**\r\n**will be added to the relationships’s value. (Note: This should not raise an**\r\n**error if part of the edges already exist).**\r\n\r\n**In case a removed_data member is specified, the values specified in this member**\r\n**will be removed from the relationship’s value. (Note: This should not raise an**\r\n**error if part of the edges do not exist).**\r\n```\r\n\r\nsuch that the following request:\r\n```json\r\n// PATCH http://api.example.com/posts/5\r\n{\r\n  \"data\": {\r\n    \"type\": \"posts\",\r\n    \"id\": \"5\",\r\n    \"attributes\": {\r\n      \"title\": \"Cool updated title\",\r\n    },\r\n    \"relationships\": {\r\n      \"tags\": {\r\n        \"added_data\": [\r\n          { \"type\": \"tags\", \"id\": \"4\" }\r\n        ],\r\n        \"removed_data\": [\r\n          { \"type\": \"tags\", \"id\": \"2\" }\r\n        ]\r\n      },\r\n      \"comments\": {\r\n        \"removed_data\": [\r\n          { \"type\": \"posts\", \"id\": \"5\" }\r\n        ]\r\n      },\r\n      \"images\": {\r\n        \"data\": [ \r\n          { \"type\": \"image\", \"url\": \"http://example.com/img.png\" }\r\n        ]\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\nwould be valid, and would have as effects:\r\n1. modify the attribute `title` of the post;\r\n2. add an (existing) `tag` to the post;\r\n3. remove a `tag` from the post;\r\n4. remove a `comment` from the post;\r\n5. replace the set of `images` attached to the post.\r\n\r\n# Pros\r\n1. Lifts the burden of \"full-replacement or multiple requests\" when updating to-many relationships;\r\n2. backwards compatible.\r\n\r\n# Cons\r\n1. 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)\r\n\r\nMore context: see [this blog post](http://lucashosseini.com/extend-jsonapi)."}}
{"actor":{"display_login":"beauby"}}