Versioning strategy for a complex internal API

Описание: This is a session given by Konstantin Yakushev at Nordic APIs 2016 Platform Summit on October 25th, in Stockholm Sweden.

Description:

API versioning is a very heated topic in API design world. Common approaches are passing version number explicitly (with a lot of fairly useless discussion on where exactly to put that number) or only introducing backwards-compatible changes.
When creating internal API for Badoo applications we found those approaches to be too limiting. Passing version number requires implementers to accommodate for all breaking changes when bumping version – even when it’s not required for business goals of that application at the time. Instead of driving value for business, application developers are in constant race to keep up with the API.

Never introducing incompatible changes is also not an option. After several feature redesigns (something that may happen at Badoo once every few weeks) protocol becomes bloated and half of the fields transmitted over the wire start being useless.

This talk is about our approach to versioning as part of client-server component negotiation. Client announces features and capabilities it supports and server replies with features status: whether they are enabled or disabled and whether they can be enabled by some user action (e. g. by buying some paid product).

Beside those componentized features, client also sends support flags such as SUPPORT_IMAGE_SIZE_VIA_URL which affects how API works. We use those flags where in typical API a version number bump would be required.

This approach allows both server and client to understand their current state and adjust their code accordingly – essentially, a tailor-made API for every client. Gathering data on feature and flag support among clients allows us to remove old code branches while continuing to evolve the API.

As a result, we are not afraid to change something when that change is required. Old clients continue to work while protocol rot is kept at low level.

In this talk I will give details on how exactly this versioning scheme work, how we test those changes, how and when we deprecate our old clients and note some stats and insights from using this scheme at Badoo for several years.

Learn more at https://nordicapis.com/blog/