V for Versioning - RubyConf ID 2017

API versioning is a simple yet sensitive issue. Doing it wrong, you'll certainly see a cold war between API and mobile app devs, not to mention angry clients with their unusable app because of API-incompatibility issue. This talk will show how to handle API versioning with care and prevent a war :)

Transcript

1. V for Versioning how we ship new feature while maintaining legacy support Harwin Prahara @hardwinder harwin@cookpad.com / hardwinder@gmail.com
2. About Me Alumnus of - Bachelor, Computer Science 2008 - 2012 - Master Program, Information Technology 2015-2017
3. About Me Software Engineer - DapurMasak (2013), Cookpad Indonesia - since 2014
4. About Me - News Headlines!
5. About Me - News Headlines!
6. About Me
7. Company Introduction
8. Oh wait, there’s an email from RubyConf committee
11. The company I work for is gold sponsor for this event anyway ¯\_(ツ)_/¯
12. Disclaimer - The story on this talk is about fictional company, called CabePedas (hot chilli ) - The story, company, all names, characters, and incidents portrayed in this talk are fictitious. No identification with actual persons (living or deceased), places, buildings, and products is intended or should be inferred.
13. About CabePedas - Global public tech company - More than 80 global software engineers - Offices: Tokyo #, Bristol$, Jakarta%, Beirut&, Alicante ', and some other global cities
14. CabePedas - Tech Stack iOS: Swift Android: Kotlin API / Web server: Ruby on Rails
15. CabePedas - Tech Map
16. CabePedas - Tech Map
17. Some Definition
18. What is API? “a set of rules that allows programmers to develop software for a particular operating system without having to be completely familiar with that operating system” Merriam webster dictionary
 https://www.merriam-webster.com/dictionary/application%20programming%20interface
19. What is API? “a set of rules that allows programmers to develop software for a particular operating system without having to be completely familiar with that operating system” Merriam webster dictionary
 https://www.merriam-webster.com/dictionary/application%20programming%20interface
20. What is API? - API provides a bridge that connects Rails developer and Android / iOS developer - There are various API format, 2 commonly used ones are: JSON and XML
21. API - common format - JSON { "recipe":{ "id" : 171006, "title" : "Sate Ayam", "story" : "Kami mengadakan pesta sate hari ini", "serving" : "4 piring", "cooking_time" : "40 menit", "created_at" : "2017-10-06T14:50:00Z", "updated_at" : "2017-10-07T15:20:00Z", "href" : "http://****/recipes/171006-Sate-Ayam" } }
22. API - common format - XML <?xml version="1.0" encoding="UTF-8" ?> <recipe> <id>171006</id> <title>Sate Ayam</title> <story>Kami mengadakan pesta sate hari ini</story> <serving>4 piring</serving> <cooking_time>40 menit</cooking_time> <created_at>2017-10-06T14:50:00Z</created_at> <updated_at>2017-10-07T15:20:00Z</updated_at> <href>http://****/recipes/171006-Sate-Ayam</href> </recipe>
23. API Server - Client Interaction
24. CabePedas API in Action - 1 Client hit an endpoint: GET /recipes/171006
25. CabePedas API in Action - 2 API server responds with JSON data
26. CabePedas Sample JSON { "recipe":{ "id" : 171006, "title" : "Sate Ayam", "story" : "Kami mengadakan pesta sate hari ini", "serving" : "4 piring", "cooking_time" : "40 menit", "created_at" : "2017-10-06T14:50:00Z", "updated_at" : "2017-10-07T15:20:00Z", "href" : "http://****/recipes/171006-Sate-Ayam"
 ... } }
27. CabePedas API in Action - 3 Client makes use of the data to render UI
28. CabePedas API in Action - 3 { "recipe":{ "id" : 171006, "title" : "Sate Ayam", "story" : "Kami mengadakan pesta sate hari ini", "serving" : "4 piring", "cooking_time" : "40 menit", "created_at" : "2017-10-06T14:50:00Z", "updated_at" : "2017-10-07T15:20:00Z", "href" : "http://****/recipes/171006-Sate-Ayam"
 ... } }
29. CabePedas API in Action - 3 { "recipe":{ "id" : 171006, "title" : "Sate Ayam", "story" : "Kami mengadakan pesta sate hari ini", "serving" : "4 piring", "cooking_time" : "40 menit", "created_at" : "2017-10-06T14:50:00Z", "updated_at" : "2017-10-07T15:20:00Z", "href" : "http://****/recipes/171006-Sate-Ayam" ... } }
30. What Could Go Wrong?
31. CabePedas - Innovative Tech Company
32. CabePedas - Innovative Tech Company - Move fast, break things
33. CabePedas - Innovative Tech Company - Move fast, break things - Do not ask permission, ask forgiveness later
34. CabePedas - Innovative Tech Company - Move fast, break things - Do not ask permission, ask forgiveness later - [Insert some other jargon here]
35. CabePedas - Moving Too Fast
36. CabePedas - Moving Too Fast - API dev team doing code-cleaning 
 (clean code movement ftw!)
37. CabePedas - Moving Too Fast - API dev team doing code-cleaning 
 (clean code movement ftw!) - Some “dusty” endpoints are removed
38. CabePedas - Moving Too Fast - API dev team doing code-cleaning 
 (clean code movement ftw!) - Some “dusty” endpoints are removed - Rolling out to users immediately 
 (cap production deploy ftw!)
39. CabePedas - Moving Too Fast - API dev team doing code-cleaning 
 (clean code movement ftw!) - Some “dusty” endpoints are removed - Rolling out to users immediately 
 (cap production deploy ftw!)
40. CabePedas - Moving Too Fast
41. CabePedas - Moving Too Fast Dude, CabePedas apps are unusable. Users are flocking our main entrance, they’re burning tires!
42. CabePedas - Moving Too Fast Uh, oh… Is that endpoint still in use?!
43. CabePedas - Moving Too Fast Not for newest app version, but we’re still rolling it out, most users have not updated yet!
44. Move fast, break things?
45. CabePedas - Restropective
46. CabePedas - Restropective - Mobile apps and API server have different roll out nature
47. CabePedas - Restropective - Mobile apps and API server have different roll out nature - Rolling out changes on server side will instantly take effect for all users - Rolling out new version of apps will only affect users who updates 
 (it takes some time for most users to update)
48. CabePedas - Restropective - Mobile apps and API server have different roll out nature - Rolling out changes on server side will instantly take effect for all users - Rolling out new version of apps will only affect users who updates 
 (it takes some time for most users to update) - This timing gap could cause
49. Post-Incident Agreement
50. CabePedas - Resolution Set Rule of Thumb
51. CabePedas - Rule #1 If API change contains breaking changes.. (Changes that will make previous app version ) Then… Bump API version Make sure next app version uses new endpoint
52. CabePedas - Rule #1 Example GET /recipes/171006 GET v2/recipes/171006 GET v3/recipes/171006
53. CabePedas - Rule #2 You can’t support legacy app forever At some point, you’ll reach a cut-off point When that time comes, make sure your users know about it
54. CabePedas - Rule #2 Example CabePedas app implements 
 a “please update” mechanism in-app
55. CabePedas - Rule #2 Example When client hits an obsolete endpoint...
56. CabePedas - Rule #2 Example When client hits an obsolete endpoint... API server will respond with 
 “hey, you’re trying to access obsolete endpoints”
57. CabePedas - Rule #2 Example When client hits an obsolete endpoint... API server will respond with 
 “hey, you’re trying to access obsolete endpoints” Client will then show “please update” screen
58. “Please Update” screen
59. “Please Update” screen
60. “Please Update” Effect
61. CabePedas - Resolution
62. Rule of thumb #1 Bump API version, if there are breaking changes #2 Tell user nicely when their app is no longer supported
63. Q&A (CabePedas is not hiring)