I've found it's a mix between the two extremes. Obviously, I can't start suddenly returning XML instead of JSON, because "I feel like it and it's cool"; it bre

I've found it's a mix between the two extremes. Obviously, I can't start suddenly returning XML instead of JSON, because "I feel like it and it's cool"; it breaks everyone horribly, so that needs to be version 2. But if you insist on upping the version effectively any time you do, you're essentially saying that any side-effect (not just output) visible can't be fixed, except by duplicating the API and creating a new version, fixing it there, and moving the callers over (if you can — this, I've found is the hardest part[1]). Often, these are things that I feel like the spec is supposed to hash out: what is it supposed to do. If it strays from the spec, that doesn't necessarily require a new version number, especially if it doesn't break things. However, it has been my experience in that even the most benign changes will break things; you've got to be able to evaluate and figure out who is not following spec, and sometimes, how bad is the effect of the change if the clients didn't like it. (Is it so bad that, even though it's to spec, I should roll back? Or should the client fix the buggy behavior they've been depending on, and we can carry on in the meantime?) [1]: Mobile clients are out there. Unlike a web page, there's no way to edit/update them — you can push a new version, but will the users upgrade? At some point, you have to cut them, I suppose, but after how long? 6 months? <2% share among the user base? the active user base? What's an active user? (and now higher ups are involved, and you're in meetings…) [also]: https://xkcd.com/1172/ https://xkcd.com/1172/