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.
40. API Refactoring!
Generalize: Buttons array instead of one button
Change global logic: Supports concrete error
types instead of generic error
Cover screw ups: All dates are now UTC
55. Continuous
versioning
0. Add new fields for new features
1. Have a list of supported things
2. Cover changes with a change flag
3. Let server control enabling and disabling
4. Create supersets of APIs for experimenting
58. On practice
Architects can do refactoring all the time
Client developers can do only minimal changes
Product owners can get exactly what they want
Backend developers …
62. On practice
Architects can do refactoring all the time
Client developers can do only minimal changes
Product owners can get exactly what they want
Backend developers can still work sanely and
easily split in parallel