Versioning strategy for a complex internal API

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.

Smarter Tech Decisions Using APIs

Smarter Tech Decisions Using APIs

API blog

High impact blog posts and eBooks on API business models, and tech advice

API conferences

Connect with market leading platform creators at our events

API community

Join a helpful community of API practitioners

API Insights Straight to Your Inbox!

Can't make it to the event? Signup to the Nordic APIs newsletter for quality content. High impact blog posts on API business models and tech advice.

Join Our Thriving Community

Become a part of our global community of API practitioners and enthusiasts. Share your insights on the blog, speak at an event or exhibit at our conferences and create new business relationships with decision makers and top influencers responsible for API solutions.