Some highlights:
* when a client first makes requests store their version, so that they don't have to worry about it * decouple features from versions, by using 'gates' (allowing for far more versions than would otherwise be possible)
I don't see why it's so hard to chuck a version in the URL. There's no great need to update the version when adding new features, only when changing existing functionality.
> It's an interesting idea but I can't see how it'd work cleanly in practise. The consumer won't even know what version they're using themselves, which makes documentation and API client updates more difficult than it should be.
To some extent, this is a design goal: most of the time, you should not need to know or care what version of the API you're on (your API's history is pretty irrelevant to a new consumer). Most API consumers just want to test out some calls, make sure they work at the time, and know that they won't break in the future. If you want to discover or set your version, you can do so easily.
> I don't see why it's so hard to chuck a version in the URL. There's no great need to update the version when adding new features, only when changing existing functionality.
It'd actually be much easier for us just chuck a version in the URL. But that would comes at the expense of ease for our users.
I think of our approach as making versions be data rather than code. It means that users using standard plugins can often upgrade without having to fork. (We also have many of our client libraries discover properties directly from the API, meaning that they very rarely need upgrading). It also means that new users never have to go and figure out "what's the current version of the API? hm, the guide I'm reading is telling me to use one that's 4 versions out-of-date — I guess I'll copy-paste the code and then modify all the URLs". (If you instead encapsulate the version in your client library, you may as well just make it a database setting.) As a general rule, a code change for a user is much more expensive than frobbing an account setting (given that it's possible to test).
[1] http://docs.aws.amazon.com/Route53/latest/APIReference/API_C...
Reading this (or watching the video) will be well worth your time.
This actually works out okay for most of our libraries. For the ones that can support it (Ruby, Python, etc), we don't hardcode the properties for any resources and instead generate objects on-the-fly when you make an API request.
In the $1 example, the libraries will just construct a Charge object without the `amount` property, since it wasn't returned in the API response.
You're right that it isn't perfect for other languages, though. We're working on making our versioning story better in our docs, libraries, webhooks, etc. (:
I'm more thinking in the idea of doing some "pre-validation" in my library to avoid an API call from the client when something is already expected to fail (like missing the amount field right now) which would not fail with a new version of the API. So I would have to adapt to each version to know that this user would require the amount field while another one would not.
Very interesting talk!
