

Move Fast, Don't Break Your API - ewang1
http://amberonrails.com/move-fast-dont-break-your-api/

======
room271
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)

~~~
beefsack
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.

~~~
ivanceras
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.

~~~
matthewarkin
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().

~~~
micro-ram
Agreed. This bit me once.

------
100k
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.

------
koopajah
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.

~~~
amfeng
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.
(:

~~~
koopajah
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_.

~~~
boucher
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.

------
zzen
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...](http://blog.heavybit.com/blog/apiary-api-design-versioning-
testing)

------
nsondhi
We also wrote a blog about the talk [http://blog.heavybit.com/blog/apiary-api-
design-versioning-t...](http://blog.heavybit.com/blog/apiary-api-design-
versioning-testing)

Very interesting talk!

------
suzyperplexus
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...](http://www.heavybit.com/library/developer-
technical/video/2014-09-30-amber-feng)

------
capkutay
I was going to say, 'Move Fast, Don't Break Anything But Your Local Code
Branch"...API works too.

