{"action":"created","issue":{"url":"https://api.github.com/repos/mozilla-services/readinglist/issues/242","labels_url":"https://api.github.com/repos/mozilla-services/readinglist/issues/242/labels{/name}","comments_url":"https://api.github.com/repos/mozilla-services/readinglist/issues/242/comments","events_url":"https://api.github.com/repos/mozilla-services/readinglist/issues/242/events","html_url":"https://github.com/mozilla-services/readinglist/issues/242","id":66108674,"number":242,"title":"Clarify conflict documentation","user":{"login":"tarekziade","id":250019,"avatar_url":"https://avatars.githubusercontent.com/u/250019?v=3","gravatar_id":"","url":"https://api.github.com/users/tarekziade","html_url":"https://github.com/tarekziade","followers_url":"https://api.github.com/users/tarekziade/followers","following_url":"https://api.github.com/users/tarekziade/following{/other_user}","gists_url":"https://api.github.com/users/tarekziade/gists{/gist_id}","starred_url":"https://api.github.com/users/tarekziade/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tarekziade/subscriptions","organizations_url":"https://api.github.com/users/tarekziade/orgs","repos_url":"https://api.github.com/users/tarekziade/repos","events_url":"https://api.github.com/users/tarekziade/events{/privacy}","received_events_url":"https://api.github.com/users/tarekziade/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":3,"created_at":"2015-04-03T08:39:47Z","updated_at":"2015-04-03T08:55:41Z","closed_at":null,"body":"The doc here http://readinglist.readthedocs.org/en/latest/api/resource.html#conflicts says \r\n\r\n```\r\nIf the a conflict occurs, an error response is returned with status 409. A existing attribute in the response gives the offending record.\r\n```\r\n\r\nThis is unclear because here http://readinglist.readthedocs.org/en/latest/api/resource.html#post-articles it says:\r\n\r\n```\r\nIf the request header If-Unmodified-Since is provided, and if the record has changed meanwhile, a 412 Precondition failed error is returned.\r\n```\r\n\r\nCan we clarify the documentation and explains exactly what happens with these scenarios (what ends in the DB and what gets back to the client body+code) :\r\n\r\n- No If-Unmodified-Since header, client A provides a record with an URL similar to an URL of a record pushed by client B a few seconds before.\r\n- If-Unmodified-Since header, client A provides a record with an URL similar to an URL of a record pushed by client B a few seconds before.\r\n- No If-Unmodified-Since header, client A provides in the same batch two different items that resolves to the same URL\r\n- If-Unmodified-Since header, client A provides in the same batch two different items that resolves to the same URL\r\n\r\n\r\n\r\n"},"comment":{"url":"https://api.github.com/repos/mozilla-services/readinglist/issues/comments/89227416","html_url":"https://github.com/mozilla-services/readinglist/issues/242#issuecomment-89227416","issue_url":"https://api.github.com/repos/mozilla-services/readinglist/issues/242","id":89227416,"user":{"login":"Natim","id":229453,"avatar_url":"https://avatars.githubusercontent.com/u/229453?v=3","gravatar_id":"","url":"https://api.github.com/users/Natim","html_url":"https://github.com/Natim","followers_url":"https://api.github.com/users/Natim/followers","following_url":"https://api.github.com/users/Natim/following{/other_user}","gists_url":"https://api.github.com/users/Natim/gists{/gist_id}","starred_url":"https://api.github.com/users/Natim/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Natim/subscriptions","organizations_url":"https://api.github.com/users/Natim/orgs","repos_url":"https://api.github.com/users/Natim/repos","events_url":"https://api.github.com/users/Natim/events{/privacy}","received_events_url":"https://api.github.com/users/Natim/received_events","type":"User","site_admin":false},"created_at":"2015-04-03T08:55:41Z","updated_at":"2015-04-03T08:55:41Z","body":"The scenarii are not related to the question above, so let me try to explain how it works:\r\n\r\nFor the readinglist your are unlikely to have a 409 because PUT has been deactivated and POST resolve to either ``201 Created`` if the articles was created or ``200 OK`` if the article already existed.\r\n\r\nYou've got a ``412 Precondition Failed`` if the resource you are applying to changed between your two calls.\r\n\r\nThey are two kinds of resources:\r\n\r\n - Collections ie. ``/articles``\r\n - Records ie. ``/articles/:id``\r\n\r\nFor the collection, the precondition failed if the collection changed. This is useful when going through pagination to now that something changed.\r\n\r\nFor records, the precondition failed if the record changed. This is useful to make sure a change doesn't override a previous change.\r\n\r\nIn the case of the readinglist the only change that should have a Precondition Header is the title change because all other conflict are handled on the server side."}}