+ JR
----- Original Message ----- From: "Richard Newman" <[email protected]> To: "Toby Elliott" <[email protected]>, [email protected] Cc: "Austin King" <[email protected]>, "Chris Karlof" <[email protected]>, [email protected] Sent: Monday, September 23, 2013 3:35:57 PM Subject: Re: API versioning strategy > This also has the benefit operationally of being able to run only the highest > version of the 1.X series and knowing that it'll talk compatibly to all the > 1.X clients. If you're using integer versions, you either have to maintain > semantically unclear maps in the backend, or maintain all the versions. Pretty much that's equivalent to putting "1" in the URL, and using "1.3" for docs, so I'm on board with that. If the wire protocol (including responses) is back-compatible, the client doesn't need to tell the server explicitly that it's a 1.3 client. My only concern with the version-first idea: it can introduce some cost in deployment and software management. Nobody wants to maintain 30 different entry points to mostly-the-same code, just because you revved a version number to change some API contract. Ideally one can segment the URL space (or use back-compatibility somehow) to allow for sensible revving: foo.com/1/users/2/eat => {v: 5, name: "bar"} I'm a huge fan of "version everything", but I'm also mindful of the friction factor that it can impose along some axes. This is mainly an issue when you're dealing with deployed clients. For web apps, foo.com/app/?v=1234 makes a ton of sense, because that version number 'ships' a new version of the client to the virtual machine in the browser; rock and roll. When you have static code that's going to stick around for two years, and you can't just say "reload the page to keep using the app", things have to be a little more mindful. Anyway, that was pretty handwavy; over to rfkelly for something a little more concrete (I hope)! -R _______________________________________________ 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
