{"action":"created","issue":{"url":"https://api.github.com/repos/HabitRPG/habitrpg/issues/4432","labels_url":"https://api.github.com/repos/HabitRPG/habitrpg/issues/4432/labels{/name}","comments_url":"https://api.github.com/repos/HabitRPG/habitrpg/issues/4432/comments","events_url":"https://api.github.com/repos/HabitRPG/habitrpg/issues/4432/events","html_url":"https://github.com/HabitRPG/habitrpg/issues/4432","id":52973893,"number":4432,"title":"API changes aren't visible enough to third-party developers/partners","user":{"login":"Alys","id":1495809,"avatar_url":"https://avatars.githubusercontent.com/u/1495809?v=3","gravatar_id":"","url":"https://api.github.com/users/Alys","html_url":"https://github.com/Alys","followers_url":"https://api.github.com/users/Alys/followers","following_url":"https://api.github.com/users/Alys/following{/other_user}","gists_url":"https://api.github.com/users/Alys/gists{/gist_id}","starred_url":"https://api.github.com/users/Alys/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Alys/subscriptions","organizations_url":"https://api.github.com/users/Alys/orgs","repos_url":"https://api.github.com/users/Alys/repos","events_url":"https://api.github.com/users/Alys/events{/privacy}","received_events_url":"https://api.github.com/users/Alys/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":4,"created_at":"2014-12-28T06:18:25Z","updated_at":"2015-04-11T05:17:02Z","closed_at":null,"body":"Recently, a change was made to HabitRPG's API that caused the Beeminder-HabitRPG integration to break (users were unable to make new HabitRPG goals in Beeminder). Beeminder staff have already fixed the problem so we don't need to investigate or change anything at our end, but this highlights the need to make API changes very obvious (ideally in advance) to third party developers. It's for HabitRPG's benefit as well - for example, if a long-time Beeminder user decides to try HabitRPG because the integration exists, we could lose a potential customer if the integration is broken.\r\n\r\nSo, this issue is for us to discuss ways that API changes can be made more visible. \r\n\r\nOne option is that third-party developers can watch our files in GitHub for any changes. If they do that, is [src/routes/apiv2.coffee](https://github.com/HabitRPG/habitrpg/blob/develop/src/routes/apiv2.coffee) the ONLY file they would need to watch to be sure of noticing ALL changes that might affect their use of the API?\r\n\r\nSomething else that could help is if we try to submit all changes to the API through pull requests rather than through direct commits. PRs are much more obvious to anyone watching the repository (that includes HabitRPG admins and devs as well as third-partiers) and so are more likely to allow API changes to be recognised. It would also be good if the title of the PR mentioned the API.\r\n\r\nI think it might also help if PRs that affect the API are left unmerged for a couple of days to give people time to comment on them and/or adjust their own code. Of course that does depend on how urgent the change is - we might not always be able to wait.\r\n\r\nWould it be practical to set up some kind of mailing list / discussion group / notice board that's dedicated to API changes? Somewhere where we can state our intentions to change the API or notifcations that we have just changed it? Or would that be more trouble and effort than it's worth?\r\n\r\nDoes anyone have any other thoughts or improvements/criticisms of these ideas?\r\n\r\n\r\n<bountysource-plugin>\r\n---\r\nWant to back this issue? **[Post a bounty on it!](https://www.bountysource.com/issues/7319318-api-changes-aren-t-visible-enough-to-third-party-developers-partners?utm_campaign=plugin&utm_content=tracker%2F68393&utm_medium=issues&utm_source=github)** We accept bounties via [Bountysource](https://www.bountysource.com/?utm_campaign=plugin&utm_content=tracker%2F68393&utm_medium=issues&utm_source=github).\r\n</bountysource-plugin>"},"comment":{"url":"https://api.github.com/repos/HabitRPG/habitrpg/issues/comments/91763875","html_url":"https://github.com/HabitRPG/habitrpg/issues/4432#issuecomment-91763875","issue_url":"https://api.github.com/repos/HabitRPG/habitrpg/issues/4432","id":91763875,"user":{"login":"Alys","id":1495809,"avatar_url":"https://avatars.githubusercontent.com/u/1495809?v=3","gravatar_id":"","url":"https://api.github.com/users/Alys","html_url":"https://github.com/Alys","followers_url":"https://api.github.com/users/Alys/followers","following_url":"https://api.github.com/users/Alys/following{/other_user}","gists_url":"https://api.github.com/users/Alys/gists{/gist_id}","starred_url":"https://api.github.com/users/Alys/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Alys/subscriptions","organizations_url":"https://api.github.com/users/Alys/orgs","repos_url":"https://api.github.com/users/Alys/repos","events_url":"https://api.github.com/users/Alys/events{/privacy}","received_events_url":"https://api.github.com/users/Alys/received_events","type":"User","site_admin":false},"created_at":"2015-04-11T05:17:02Z","updated_at":"2015-04-11T05:17:02Z","body":"I do love RSS although it's so out of use now I'd temporarily forgotten about it... :blush:"}}