+1 to reducing the scope of this conversation to REST api versioning only (we can tackle DOM/js in other threads, and iiuc that's not a problem we need to solve right now)
+1 to prepending '/vX' (major version only, include the v) lloyd On Sep 24, 2013, at 3:29 AM, Mark Mayo <[email protected]> wrote: > In my experience, there's no such thing as minor versions of wire protocols. > Either you changed the API (and broke somebody's client - guaranteed) or you > didn't change the API. (I'm sure there's examples of purely additive API > changes that broke nothing and hence fit the .minor criteria, but I'm not > sure I can name one myself) > > I'm a fan of date-based versions (20130913) as popularized by AWS, but I'm > cool with a /v1 in the URL of a non-RESTy API too. > > I also like an accept-version header from the server to also include minor > (accept-version: ~1.0), but maybe that's only cool for REST, I don't know. > > -Mark > > > > On Mon, Sep 23, 2013 at 5:10 PM, Ryan Kelly <[email protected]> wrote: > On 24/09/2013 9:50 AM, Ryan Kelly wrote: > > Forwarding input from JR, since this discussion seems to be spanning two > > different mailing lists. > > I heartily endorse all of JRs comments here, with one tweak. > > > Your version is: > > > > Major.Minor.Build > > > > Major - Introduces at least one non-backwards compatible function that > > will break clients. This is non-negotiable. There are no "small" > > changes. Since your unit tests are based on your published API (they > > are, right?) if they break, you change your Major. > > > > Minor - Introduces at least one new feature or function that adds to the > > existing API. > > > > Build - Fixes a bug to bring existing elements more inline with > > published specifications. > > > > The URL value contains only the Major version. Why? Because if you add a > > new feature, you're not breaking anything. If the feature didn't exist > > before, then older clients will never have called it. If you are > > breaking something, you're using a new Version. > > In our world of open-source federated services, there's no guarantee > that that the particular server you're talking to is running the latest > version of the code. We have to worry about "older servers" and well as > "older clients". > > For this reason I advocate vMAJOR.MINOR in the URL to reduce the chance > of a silent version expectation mismatch. > > It is kinda ugly though, so two alternatives: > > * Don't do minor version revs. Any non-bugfix change bumps the major > version number, and we try hard to keep these infrequent. > > * Very carefully write your clients so they can take advantage of any > changes introduced in a minor version, but will operate correctly > against older servers. > > > > Cheers, > > Ryan > > _______________________________________________ > Sync-dev mailing list > [email protected] > https://mail.mozilla.org/listinfo/sync-dev > > _______________________________________________ > Sync-dev mailing list > [email protected] > https://mail.mozilla.org/listinfo/sync-dev
_______________________________________________ Sync-dev mailing list [email protected] https://mail.mozilla.org/listinfo/sync-dev
