This is a fascinating article. Some innovative stuff to deal with the difficult problem of how to innovate without breaking existing customers.
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)
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.
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.
I was at her presentation of this on Wednesday and it was great to get a peek at how Stripe does their API development, since what they've built has been really impressive.
Reading this (or watching the video) will be well worth your time.
Does it also mean that when doing an API client library for stripe you have to handle all this complexity about versionning? Because if someone updates to the latest version of the library but still wants to use the old way of creating a charge (staying on the example where charge would now always be 1$) he would want to be able to do it without having to find an older version of the library that supported this API version.
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. (:
[+] [-] room271|11 years ago|reply
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)
[+] [-] beefsack|11 years ago|reply
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.
[+] [-] 100k|11 years ago|reply
Reading this (or watching the video) will be well worth your time.
[+] [-] koopajah|11 years ago|reply
[+] [-] amfeng|11 years ago|reply
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. (:
[+] [-] zzen|11 years ago|reply
[+] [-] nsondhi|11 years ago|reply
Very interesting talk!
[+] [-] suzyperplexus|11 years ago|reply
[+] [-] capkutay|11 years ago|reply