Move Fast, Don't Break Your API(amberonrails.com)
amberonrails.com
Move Fast, Don't Break Your API
http://amberonrails.com/move-fast-dont-break-your-api/
15 comments
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 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 work at Stripe.)
> 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...
> 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...
I think he means, that when a client make a request, the API server will now what version of the API it is calling, then whatever data the api call created/updated, the version of the the API being used will also be stored into the data.
One thing is that Stripe's documentation only shows the latest version, not the version of the API you are on. So for instance the API docs will show that the way you create a refund is charge->refunds->create(), but if your first request was before multiple refunds were a thing that api call would error since the api is expecting charge->refund().
Agreed. This bit me once.
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.
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.
Hi! OP here.
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. (:
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 understand how you handle it on your end but let's assume I decide to build an API for a language you don't support yet. In a few months when you add new versions of the API where some fields become optional or mandatory, then won't I have to know all this as the library developer and handle each case? Because some of my users would expect to still be able to send the charge amount while others would not.
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.
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.
Yeah, we specifically designed this setup with your situation in mind. As the author of a library, you can specify the version you want to use. So your code will work on any account, regardless of what that account's version is set to.
Cool article & design approach. I've really enjoyed the Heavybit talk a couple weeks back, wrote about it today at HB blog: http://blog.heavybit.com/blog/apiary-api-design-versioning-t...
We also wrote a blog about the talk http://blog.heavybit.com/blog/apiary-api-design-versioning-t...
Very interesting talk!
Very interesting talk!
Amber also did this as a presentation at Heavybit if you're interested in seeing it http://www.heavybit.com/library/developer-technical/video/20...
I was going to say, 'Move Fast, Don't Break Anything But Your Local Code Branch"...API works too.
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)