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.

1. Versioning strategy
for a complex internal API
Konstantin Yakushev

2. 2014 – Everada – partner API
2015 – Timepad – public API
2016 – Badoo – internal API (apps)
Konstantin

3. Plan
Badoo API
Usual public API versioning
Our internal API versioning scheme
Practical considerations

4. The original, largest and leading
dating network

5. API
Evolving since 2010
RPC-style non-restful protobuf-based
570 commands
1200 classes
9 releases each week

6. ~ 5 last versions
last iOS 7 version
~ 10 last versions
last Android 2.x version
~ 2 last versions
last WP7 version
Badoo versions

7. Versioning strategy
for a complex internal API
Konstantin Yakushev

8. Typical
versioning

9. 1)http://api.example.com/orders
2) Collect nice-to-have breaking changes
3) Announce new version with all of them
4)http://api.example.com/v2/orders
5) Slowly deprecate v1
Typical versioning

10. http://api.example.com/v2/orders
http://api.example.com/orders/v2
http://api.example.com/orders
X-Api-Version: 2
http://api.example.com/orders
Accepts: application/vnd.example.v2+json
Typical versioning

11. 1)http://api.example.com/orders
2) Collect nice-to-have breaking changes
3) Announce new version with all of them
4)http://api.example.com/v2/orders
5) Slowly deprecate v1
Typical versioning
The least important step

12. 1)http://api.example.com/orders
2) Collect nice-to-have breaking changes
3) Announce new version with all of them
4)http://api.example.com/v2/orders
5) Slowly deprecate v1
Typical versioning

13. There is no v2

14. Continuous
versioning

15. Problem:
new property
supersedes old

16. Verification ✔

17. Verification ✅

18. user: {
is_verified: true | false
}
user: {
verification_status: NONE | PARTIAL | FULL
}

19. user: {
is_verified: true | false
}
user: {
is_verified: true | false
verification_status: NONE | PARTIAL | FULL
}

20. user_request: { // like GraphQL
fields: [verification_status]
}
user: {
verification_status: NONE | PARTIAL | FULL
}

21. user_request: { // like GraphQL
fields: [is_verified]
}
user: {
is_verified: true | false
}

22. Problem:
new property
supersedes old
Add a new field.
Make clients select which fields they want.

23. Problem:
similar structures
of different types

24. Badoo has
34 types
of banners

25. banner: {
header: "Get extra…",
pictures: [<pics>],
text: "Make it easy…",
buttons: [<button>]
}

28. banner: {
header: "Get extra…",
pictures: [<pics>],
text: "Make it easy…",
buttons: [<button>],
type: "EXTRA_SHOWS"
}

29. user_list_request: {
fields: [banners]
}
user_list: {
banners: [<unknown banner>]
}

30. user_list_request: {
fields: [banners_v24]
}
user_list: {
banners_v24: [<banner>]
}

31. user_list_request: {
fields: [banners],
supported_banners: [EXTRA_SHOWS]
}
user_list: {
banners: [<extra shows banner>]
}

32. Client
specifics
This banner is mobile-only.
Simply not set as supported
by desktop web.

33. Problem:
similar structures
of different types
Release a new thing on server whenever.
Make clients send supported types explicitly.

34. Problem:
business logic
changes

36. user_request: {
fields: [photos]
}
user: {
photos: [ <photo 1>, <photo 2>]
}

38. user_request: {
fields: [photos],
supported_changes: [VIDEOS_IN_PHOTOS]
}
user: {
photos: [ <photo 1>, <video 1>, <photo 2>, …]
}

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

41. Problem:
business logic
changes
Do changes behind version flag.
Make client control those flags.

42. Problem:
simultaneous
release on clients

43. Video
calling

44. Release plan
Web – releases Sept 3
Android – releases Sept 1
Windows – releases Aug 20
iOS – releases Sept 7

45. startup_request: {
supported_features: [VIDEO_CALLS, GIFS]
}
startup: {
allowed_features: [GIFS] // client will turn
// video calls off
}

46. startup_request: {
supported_features: [VIDEO_CALLS, GIFS]
}
startup: {
allowed_features: [GIFS, VIDEO_CALLS]
// feature released
}

47. Negotiate feature
Simultaneous launch
A/B-tests
Spam-filtering
Split paid/unpaid users

48. Problem:
simultaneous
release on clients
Negotiate feature with server.
Once you see that enough clients support it,
launch.

49. Problem:
quick experiments

50. What’s my
chances

51. https://bit.ly/badoo-wp

52. user: {
verified_status: NONE | PARTIAL | FULL,
}
user: {
verified_status: NONE | PARTIAL | FULL,
experimental_chances: 57, // only on windows
}

53. Problem:
quick experiments
Create a superset experimental API
Use it only on one platform

54. 1)http://api.example.com/orders
2) Collect nice-to-have breaking changes
3) Announce new version with all of them
4)http://api.example.com/v2/orders
5) Slowly deprecate v1
Typical versioning

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

56. On practice?

57. On practice
257 feature flags
161 negotiable features
Apified web client in 2015

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 …

59. Suggest
upgrading

60. Force
upgrading

61. Dashboard
4.44 4.43 4.42 4.41 3.57
VIDEOS_IN_PHOTOS + +
BUTTONS_ARRAY + + + + +
ALL_DATES_ARE_UTC

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

63. Thank you!
http://no-v2.kojo.ru