{"action":"created","issue":{"url":"https://api.github.com/repos/matrix-org/matrix-doc/issues/68","labels_url":"https://api.github.com/repos/matrix-org/matrix-doc/issues/68/labels{/name}","comments_url":"https://api.github.com/repos/matrix-org/matrix-doc/issues/68/comments","events_url":"https://api.github.com/repos/matrix-org/matrix-doc/issues/68/events","html_url":"https://github.com/matrix-org/matrix-doc/pull/68","id":108383952,"number":68,"title":"Swagger documentation for the v2 sync API","user":{"login":"NegativeMjark","id":904009,"avatar_url":"https://avatars.githubusercontent.com/u/904009?v=3","gravatar_id":"","url":"https://api.github.com/users/NegativeMjark","html_url":"https://github.com/NegativeMjark","followers_url":"https://api.github.com/users/NegativeMjark/followers","following_url":"https://api.github.com/users/NegativeMjark/following{/other_user}","gists_url":"https://api.github.com/users/NegativeMjark/gists{/gist_id}","starred_url":"https://api.github.com/users/NegativeMjark/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/NegativeMjark/subscriptions","organizations_url":"https://api.github.com/users/NegativeMjark/orgs","repos_url":"https://api.github.com/users/NegativeMjark/repos","events_url":"https://api.github.com/users/NegativeMjark/events{/privacy}","received_events_url":"https://api.github.com/users/NegativeMjark/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":10,"created_at":"2015-09-25T18:33:27Z","updated_at":"2015-09-29T18:26:15Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/matrix-org/matrix-doc/pulls/68","html_url":"https://github.com/matrix-org/matrix-doc/pull/68","diff_url":"https://github.com/matrix-org/matrix-doc/pull/68.diff","patch_url":"https://github.com/matrix-org/matrix-doc/pull/68.patch"},"body":"A first attempt at documenting the v2 /sync APIs as swagger. There are a few differences with the API described in #6.\r\n\r\n1) The \"event_map\" has been moved to the top level to be an \"events\" array. This removes the arbitrary division between the different kinds of events in how they are handled by the API, but provides the same de-duplication as in #6. Since some events lack event_ids we index by position within the array rather than by event id.\r\n\r\n2) The \"events\" key within the room object has been renamed to \"timeline\" to avoid confusion with the state event key.\r\n\r\n3) The \"public_user_data\", \"private_user_data\", \"ephemeral\", \"state\" and \"timeline\" keys have been made objects in the expectation that subsequent versions of the specification will add pagination of the individual components of the sync.\r\n\r\n4) The \"limited\" and \"prev_batch\" keys have been moved inside the \"timeline\" object since they are specific to the pagination of the \"timeline\". However equivalent keys have not been added to the other batches of events such as \"state\" since we won't know what the actual structure of pagination for those requests will look like until we implement them.\r\n\r\n5) The \"limit\" parameter has been moved into the filter definition under the timeline section.\r\n\r\n6) The \"sort\" key has been omitted from the request. It may be useful to add it in a subsequent iteration, but I don't see the value in speculative feature additions to the specification. We can always add keys later.\r\n\r\n7) The \"filter_.*\" parameter has been omitted. We may find reason to add them in a subsequent specification.\r\n\r\n8) The \"gap\" parameter has been omitted. We can add it in a subsequent update."},"comment":{"url":"https://api.github.com/repos/matrix-org/matrix-doc/issues/comments/144146472","html_url":"https://github.com/matrix-org/matrix-doc/pull/68#issuecomment-144146472","issue_url":"https://api.github.com/repos/matrix-org/matrix-doc/issues/68","id":144146472,"user":{"login":"NegativeMjark","id":904009,"avatar_url":"https://avatars.githubusercontent.com/u/904009?v=3","gravatar_id":"","url":"https://api.github.com/users/NegativeMjark","html_url":"https://github.com/NegativeMjark","followers_url":"https://api.github.com/users/NegativeMjark/followers","following_url":"https://api.github.com/users/NegativeMjark/following{/other_user}","gists_url":"https://api.github.com/users/NegativeMjark/gists{/gist_id}","starred_url":"https://api.github.com/users/NegativeMjark/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/NegativeMjark/subscriptions","organizations_url":"https://api.github.com/users/NegativeMjark/orgs","repos_url":"https://api.github.com/users/NegativeMjark/repos","events_url":"https://api.github.com/users/NegativeMjark/events{/privacy}","received_events_url":"https://api.github.com/users/NegativeMjark/received_events","type":"User","site_admin":false},"created_at":"2015-09-29T18:26:15Z","updated_at":"2015-09-29T18:26:15Z","body":"> We probably want to { } the rooms key like we've done on the rest because A: consistency and B: pagination of rooms when we finally get there\r\n\r\n@Kegsay Do you have any suggestions on what to call the inner key? ``{\"rooms\": {\"rooms\":[...]}}`` seems a bit wrong."}}