APIs as infrastructure: future-proofing Stripe with versioning

As a raw concept, I really like this idea. Let's say you're bumping from 2.5 to 2.6 and there's a breaking change in-between.

You replace the old api code with a new thin layer that consumes 2.6 and puts it in 2.5 format. This would be easy to write a series of tests for to make sure that 2.5 is still providing what it should, and it has the added benefit of giving your engineers the opportunity to consume the new api internally in a structured way, so that would be a good way to catch any bugs you might not otherwise find.

And of course, the 2.4 version already only consumes the 2.5 version, so it's turtles all the way down.

That's a great concept. You would have to still deprecate APIs or provide an incentive for users to update to the newest version, otherwise the oldest versions would create a long chain of requests that add unnecessary overhead. But otherwise I love it.

To the point of the XSLT being so trivial that maybe you didn't need the change, I recall one of our changes being around a field that got split into 2 fields. We certainly could have put special case code in to handle old version vs new version, but the great thing is, we didn't have to put that code in. It really keeps the interface a lot cleaner.

Also, XSLT is capable of some pretty advanced transformations, so I wouldn't dismiss it out of hand as triviality.

Regarding the documentation, we build all our docs off Javadoc and a few annotations, so docs were always current. As a bonus, when your Javadoc is used to generate public docs, you tend to treat it with more respect than Javadoc usually gets.

We did something like this in the on a message bus: the channels had the version in the name and and older version service always asked for the same data on the next version channel (the only other version it knew about), and then transformed it before sending it on. This meant you never had to maintain anything accept your newest version. It also meant you could never completely remove data because versions going obsolete needed a way to find or derive it to create their older version.

Additionally, devs would need to specify what their changes were independent of where they made the change, which meant that our API reference (which can display warning flags next to changed fields) was missing changes. With the new system we can enforce that the change being made is properly documented, since we know that it's encapsulated inside of the change class itself.

Stripe probably tracks the relative usage of each API version. If they found a lot of their users were stuck on an old version, that would point to a bigger problem than just some per-request overhead.

- They apply transformations to convert responses from the current version to the previous version, step by step.

- This means the overhead for old versions only applies to consumers of the old version.

- They support all versions going back 6 years.

https://github.com/bwillis/versioncake

"Version Cake is an unobtrusive way to version APIs in your Rails or Rack apps."

"We also tailor our API reference documentation to specific users. It notices who is logged in and annotates fields based on their account API version."

I don't understand why they didn't just use the X-GitHub-Media-Type header as a request header.

Have run into more than one issue with the vary: Accept being ignored, resulting in everyone getting the result from the first man in regardless of header variance.

Especially noticeable when we tried supporting both JSON and XML via the accepts header, with the version in the mime.