10) Lonestar ElixirConf 2018 - User-centered API Versioning - Niall Burkley

User-centered API Versioning - @nburkley

API versioning is hard. Upgrading versions usually involves pain, for a public-facing API, that pain is usually borne by the customer depending on our API. Instead we’re trying to take the pain out of versioning an API, at least for the user.

Inspired by Stripe’s API (APIs as infrastructure: future-proofing Stripe with versioning), we’ve been working on implementing rolling, ‘point-in-time’ versioning for our API. It allows new features and changes to be made to the API regularly, instead of having to wait for a major version upgrade. But more importantly, it keeps the whole process simple for users. Users only need to think about versioning if they want to. They can build an integration when they sign up, and know it will continue to work without needing changes. If they want new features they can upgrade to newer versions on their own timeline.

Implementing multiple versions of an API sounds like a terrible idea. Just the thought of branching business logic in multiple places based on what version you’re serving makes me shudder. Instead of implementing multiple versions, we can implement just one version, the latest version, and layer the older versions on top of this.

Functional languages are great for transforming data, and if you’re using Elixir for Plug-based web applications this pattern works very nicely. Phoenix is a perfect example of this - it’s basically a collection of plugs that transform a connection as it makes it’s way through the application.

With this in mind, using elixir and transformation modules, we can step through versions by transforming our requests and responses. We’ve been using this to keep our API customers happy and our codebase clean and I’d love to talk more about it.

Audience: Beginner, Intermediate

All Talks Link: 0) Lonestar ElixirConf 2018 Talks