Versioning strategy for a complex internal API (Konstantin Yakushev)
-
Upload
nordic-apis -
Category
Technology
-
view
41 -
download
0
Transcript of Versioning strategy for a complex internal API (Konstantin Yakushev)
![Page 1: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/1.jpg)
Versioning strategyfor a complex internal API
Konstantin Yakushev
![Page 2: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/2.jpg)
2014 – Everada – partner API
2015 – Timepad – public API
2016 – Badoo – internal API (apps)
Konstantin
![Page 3: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/3.jpg)
PlanBadoo API
Usual public API versioning
Our internal API versioning scheme
Practical considerations
![Page 4: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/4.jpg)
The original, largest and leadingdating network
![Page 5: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/5.jpg)
APIEvolving since 2010
RPC-style non-restful protobuf-based
570 commands
1200 classes
9 releases each week
![Page 6: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/6.jpg)
~ 5 last versionslast iOS 7 version
~ 10 last versionslast Android 2.x version
~ 2 last versionslast WP7 version
Badoo versions
![Page 7: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/7.jpg)
Versioning strategyfor a complex internal API
Konstantin Yakushev
![Page 8: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/8.jpg)
Typicalversioning
![Page 9: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/9.jpg)
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
![Page 10: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/10.jpg)
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
![Page 11: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/11.jpg)
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
![Page 12: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/12.jpg)
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
![Page 13: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/13.jpg)
There is no v2
![Page 14: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/14.jpg)
Continuousversioning
![Page 15: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/15.jpg)
Problem:new propertysupersedes old
![Page 16: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/16.jpg)
Verification✔
![Page 17: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/17.jpg)
Verification✅
![Page 18: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/18.jpg)
user: {is_verified: true | false
}
user: {verification_status: NONE | PARTIAL | FULL
}
![Page 19: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/19.jpg)
user: {is_verified: true | false
}
user: {is_verified: true | falseverification_status: NONE | PARTIAL | FULL
}
![Page 20: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/20.jpg)
user_request: { // like GraphQLfields: [verification_status]
}
user: {verification_status: NONE | PARTIAL | FULL
}
![Page 21: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/21.jpg)
user_request: { // like GraphQLfields: [is_verified]
}
user: {is_verified: true | false
}
![Page 22: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/22.jpg)
Problem:new propertysupersedes oldAdd a new field.
Make clients select which fields they want.
![Page 23: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/23.jpg)
Problem:similar structuresof different types
![Page 24: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/24.jpg)
Badoo has34 typesof banners
![Page 25: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/25.jpg)
banner: {header: "Get extra…",pictures: [<pics>],text: "Make it easy…",buttons: [<button>]
}
![Page 26: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/26.jpg)
![Page 27: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/27.jpg)
![Page 28: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/28.jpg)
banner: {header: "Get extra…",pictures: [<pics>],text: "Make it easy…",buttons: [<button>],type: "EXTRA_SHOWS"
}
![Page 29: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/29.jpg)
user_list_request: {fields: [banners]
}
user_list: {banners: [<unknown banner>]
}
![Page 30: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/30.jpg)
user_list_request: {fields: [banners_v24]
}
user_list: {banners_v24: [<banner>]
}
![Page 31: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/31.jpg)
user_list_request: {fields: [banners],supported_banners: [EXTRA_SHOWS]
}
user_list: {banners: [<extra shows banner>]
}
![Page 32: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/32.jpg)
Client specificsThis banner is mobile-only.Simply not set as supportedby desktop web.
![Page 33: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/33.jpg)
Problem:similar structuresof different typesRelease a new thing on server whenever.
Make clients send supported types explicitly.
![Page 34: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/34.jpg)
Problem:business logic changes
![Page 35: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/35.jpg)
![Page 36: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/36.jpg)
user_request: { fields: [photos]
}
user: {photos: [ <photo 1>, <photo 2>]
}
![Page 37: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/37.jpg)
![Page 38: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/38.jpg)
user_request: { fields: [photos],supported_changes: [VIDEOS_IN_PHOTOS]
}
user: {photos: [ <photo 1>, <video 1>, <photo 2>, …]
}
![Page 39: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/39.jpg)
![Page 40: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/40.jpg)
API Refactoring!Generalize: Buttons array instead of one buttonChange global logic: Supports concrete error types instead of generic errorCover screw ups: All dates are now UTC
![Page 41: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/41.jpg)
Problem:business logic changesDo changes behind version flag.Make client control those flags.
![Page 42: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/42.jpg)
Problem:simultaneous release on clients
![Page 43: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/43.jpg)
Video calling
![Page 44: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/44.jpg)
Release planWeb – releases Sept 3
Android – releases Sept 1
Windows – releases Aug 20
iOS – releases Sept 7
![Page 45: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/45.jpg)
startup_request: { supported_features: [VIDEO_CALLS, GIFS]
}
startup: {allowed_features: [GIFS] // client will turn
// video calls off}
![Page 46: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/46.jpg)
startup_request: { supported_features: [VIDEO_CALLS, GIFS]
}
startup: {allowed_features: [GIFS, VIDEO_CALLS]
// feature released}
![Page 47: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/47.jpg)
Negotiate featureSimultaneous launch
A/B-tests
Spam-filtering
Split paid/unpaid users
![Page 48: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/48.jpg)
Problem:simultaneous release on clientsNegotiate feature with server.
Once you see that enough clients support it,launch.
![Page 49: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/49.jpg)
Problem:quick experiments
![Page 50: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/50.jpg)
What’s mychances
![Page 51: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/51.jpg)
https://bit.ly/badoo-wp
![Page 52: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/52.jpg)
user: {verified_status: NONE | PARTIAL | FULL,
}
user: {verified_status: NONE | PARTIAL | FULL,experimental_chances: 57, // only on windows
}
![Page 53: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/53.jpg)
Problem:quick experimentsCreate a superset experimental API
Use it only on one platform
![Page 54: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/54.jpg)
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
![Page 55: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/55.jpg)
Continuous versioning0. 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
![Page 56: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/56.jpg)
On practice?
![Page 57: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/57.jpg)
On practice257 feature flags
161 negotiable features
Apified web client in 2015
![Page 58: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/58.jpg)
On practiceArchitects can do refactoring all the time
Client developers can do only minimal changes
Product owners can get exactly what they want
Backend developers …
![Page 59: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/59.jpg)
Suggestupgrading
![Page 60: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/60.jpg)
Forceupgrading
![Page 61: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/61.jpg)
Dashboard4.44 4.43 4.42 4.41 3.57
VIDEOS_IN_PHOTOS + +BUTTONS_ARRAY + + + + +ALL_DATES_ARE_UTC
![Page 62: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/62.jpg)
On practiceArchitects 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 andeasily split in parallel
![Page 63: Versioning strategy for a complex internal API (Konstantin Yakushev)](https://reader035.fdocuments.net/reader035/viewer/2022062823/5872d2331a28ab74188b5453/html5/thumbnails/63.jpg)
Thank you!
http://no-v2.kojo.ru