API Change Strategy
Download as PPTX, PDF0 likes351 views
The document discusses the idea that versioning is often misused as a solution to software problems, leading to more complexity. It highlights essential strategies for managing software changes without breaking existing functionality and the importance of version numbers in identifying software capabilities. The author, Asbjørn Ulsberg, emphasizes that careful change management, rather than versioning, is key for successful web and API development.
API Change Strategy
- 1. GET /presentation HTTP/1.1 HTTP/1.1 200 OK Content-Type: application/json { "what": "Versioning is a Red Herring", "where": "NDC Lightning", "when": "2017-10-26" }
- 2. Asbjørn Ulsberg Business Architect Web, API, Interfaces
- 3. Some people, when confronted with a problem, think “I know, I’ll use versioning.” Now they have 2.1.0 problems.
- 5. All software should have a version number
- 6. The version number identifies the capabilities of the software
- 7. 60 Years
- 9. Without a version number, chaos ensues
- 10. should have version numbersWeb Right? sitesAPIs
- 13. Web APIs are not statically linked at compile time
- 14. A globally distributed web service is not like a local software library
- 18. Thought experiment https://www.example.com/ https://api.example.com/
- 19. Hidden costs of versioning ?
- 20. Time Cost
- 21. Scrap your versioning strategyVersioning is a Red Herring
- 23. Change Strategy 1 2 3 4 5
- 24. Change Strategy 1. What to version ✓ ✓ ✓ ✓
- 25. Change Strategy 1. What to version ✗ ✗ ✗ {…}
- 26. Change Strategy 1. You must not take anything away 2. You must not change processing rules 3. You must not make optional things required 4. Anything you add must be optional 2. Extension rules
- 27. Change Strategy 1. You must not take anything away 2. You must not change processing rules 3. You must not make optional things required 4. Anything you add must be optional 2. Extension rules
- 28. Change Strategy 3. Breaking changes {…}*URI {…}
- 29. Change Strategy 3. Breaking changes
- 31. Change Strategy 5. Communication plan
- 32. POST /ndc HTTP/1.1 Content-Type: application/json { "aquire": "Knowledge", "from": "NDC Lightning", "when": "2017-10-26" }
- 34. Change Strategy To The Rescue!
- 35. acquire acquireaquire 1 2 3 4 5678 $ …⬆acquireaquire 9 10
Editor's Notes
- #2: Hello! I'm going to talk a bit about how, in the world of distributed software, versioning is a red herring.
- #3: I’m Asbjørn Ulsberg, Business Architect for Web, API design and interfaces. In PayEx.
- #4: I’ll start off with this quote from Brandon Byars https://martinfowler.com/articles/enterpriseREST.html
- #5: Now, let me make a few claims about software and versioning some of you might agree with
- #6: All software should have a version number
- #7: The version number identifies the capabilities of the software
- #8: We have been giving software version numbers for approximately 60 years, at least since Fortran II came out in 1958. http://www.technologizer.com/2009/07/14/version-numbers/
- #9: Even things that aren’t software have version numbers these days http://thisisfivesee.blogspot.no/2013/11/new-media-and-government-relations.html https://twitter.com/eynews/status/791232910766534656
- #10: Without a version number, chaos ensues
- #11: APIs should have version numbers Web APIs should also have version numbers Right? What if we replace "APIs" with "sites"? Should web sites have version numbers?
- #12: When was the last time you saw a web site with a version number?
- #13: When we never see a v1 in a web site, why is it so common in an API? Aren’t JSON and HTML served over the exact same infrastructure? What’s different?
- #14: Because web APIs, unlike software libraries, are NOT statically linked at compile time, we should perhaps think differently about how we version them.
- #15: A globally distributed web service such as a web API is not like a locally linked software library. They are both software, but everything from how they are developed and deployed to how they are hosted is usually completely different. Therefore, shouldn’t how we version it be different too?
- #16: So, here’s a thought experiment
- #17: If web sites can exist without a version number
- #18: Perhaps web APIs can too?
- #19: Perhaps web APIs can too?
- #20: There are hidden costs to versioning: There’s a higher maintenance cost, because a versioned codebase is a larger codebase. Each version of your API needs to be independently developed, patched, documented and deployed. Broad-stroke API versioning will give resources in the API that hasn’t changed a new version, creating an exponentially larger API surface to maintain than a more fine-grained strategy. If all versions share the same codebase, all versions needs to be taken into consideration when touching any part of the code, making development slower and more bug-ridden. All of this leads to sad and discontent developers, which are less productive and less engaged, and that can have a huge cost. Since version numbers hide the fact that the new API does not support the features of the old one, there’s little incentive to figure out how to deal with breaking changes other than minting a new version number. And for the same reason, there’s no incentive to figure out answers to questions like how: Customers are notified of changes Or how they are incentivised to upgrade Or how we measure which features the customers are using. “Maintenance Services” by Setyo Ari Wibowo from the Noun Project: https://thenounproject.com/term/maintenance-services/739684/ “Sad” by Adil Siddiqui from the Noun Project: https://thenounproject.com/term/sad/22084/
- #21: And as we know, the longer we postpone answering questions like these The more difficult and expensive they can become to figure out. Therefore, we should try figure them out early. Picture credit: https://www.pexels.com/photo/brass-round-7-stack-coins-40140/
- #22: Therefore I’d like to propose that you scrap your simplistic versioning strategy. Because versioning itself is a red herring. Picture credit: http://www.todayifoundout.com/index.php/2016/05/origins-phrase-red-herring/
- #23: Instead of a Versioning Strategy You should have a Change Strategy
- #24: A Change Strategy consists of 5 principles. You figure out what to version You define some extension rules You define some rules for how to introduce breaking changes Monitor feature usage And you create a Communication plan Credit to Zdenek Nemec “Rewrite” by Arthur Shlain from the Noun Project: https://thenounproject.com/term/rewrite/104323/ “Puzzle” by Nikita Kozin from the Noun Project: https://thenounproject.com/term/puzzle/683905/ “Unlink” by Icon Depot from the Noun Project: https://thenounproject.com/term/unlink/1196171/ “Find social” by shashank singh from the Noun Project: https://thenounproject.com/term/find-social/670010/ “Communication” by Kamal from the Noun Project: https://thenounproject.com/term/communication/1251620/
- #25: Client has a version Message format has a version Server has a version The documentation (API description) has a version Credit to Zdenek Nemec “Computer” by Bhima from the Noun Project: https://thenounproject.com/term/computer/1268454/ “Message” by Trident from the Noun Project: https://thenounproject.com/term/message/1215806 “Server” by Agrahara from the Noun Project: https://thenounproject.com/term/server/1124228/ “Document” by andriwidodo from the Noun Project: https://thenounproject.com/term/document/988366/
- #26: Resources don't have a version Relations between resources don't have a version The API itself doesn’t have a version “Document” by Astonish from the Noun Project: https://thenounproject.com/term/document/1167518/ “Link” by Kavya from the Noun Project: https://thenounproject.com/term/link/1244043/ “API” by Yu luck from the Noun Project: https://thenounproject.com/term/api/410844/
- #27: The extension rules of a change strategy are simple: You must not take anything away You must not change processing rules You must not make optional things required Anything you add must be optional Credit to Zdenek Nemec.
- #28: Unless you’re using hypermedia, in which case the two last points don’t apply anymore. Credit to Zdenek Nemec.
- #29: So, how do you introduce a breaking change? Well, if a change to: Resource Identifier (the URI) including any query parameters and their semantics. Resource metadata (such as the HTTP headers). Resource data (such as the HTTP body) fields and their semantics. Actions the resource affords (e.g., available HTTP Methods). Or relations with other resources (e.g., Links). If any of these violate the extension rules enumerated earlier: ⇒ Create a new resource Credit to Zdenek Nemec. “Document” by Astonish from the Noun Project: https://thenounproject.com/term/document/1167518/ “Tags” by KΛPKLΛM from the Noun Project: https://thenounproject.com/term/tags/148915/ “Press the button” by andriwidodo from the Noun Project: https://thenounproject.com/term/press-the-button/949825/ “New document” by Tomas Knopp from the Noun Project: https://thenounproject.com/term/new-document/511524/
- #30: If the message format itself changes ⇒ Use content negotiation Credit to Zdenek Nemec. “Business Meeting” by Robiul Alam from the Noun Project: https://thenounproject.com/term/business-meeting/1303450/
- #31: Monitor usage of your API Identify usage of deprecated features HTTP access logs are a great source of information Especially if you’re using hypermedia, because you’ll have more links and resources in your API, giving you more detail about what’s going on. “Find social” by shashank singh from the Noun Project: https://thenounproject.com/term/find-social/670010/ “Crosshair” by Veronika Krpciarova from the Noun Project: https://thenounproject.com/term/crosshair/449540/ “Document” by Astonish from the Noun Project: https://thenounproject.com/term/document/1167518/
- #32: When you change your API you should have a clear plan on how to communicate the change to your customers. Newsletter Dashboard the customer sees regularly API Documentation Regardless of whether the communication is due to new features or breaking changes, you need to communicate with your customers. “Newsletter” by Setyo Ari Wibowo from the Noun Project: https://thenounproject.com/term/newsletter/1079396/ “Admin panel” by Creative Stall from the Noun Project: https://thenounproject.com/term/admin-panel/995816/
- #33: So let’s look at how this might work like in practice. Say we have this JSON document out in the wild. Then we notice the missing ’c’ in “aquire”.
- #34: What do we do? Image credit: https://www.youtube.com/watch?v=lFjWA5w74nY
- #35: Change Strategy To The Rescue! Image credit: http://rescuedbycode.com/unix-and-perl-book
- #36: First we add support for the correct spelling of acquire to the API. Then we fix the spelling in the documentation. Then we notify the customers of the typo and that they should update their client software. Then we add monitoring of the usage of the typo field. Time passes Then we notify customers still using the typo field. More time passes We then incentivise the customers still using the typo field With Money, Plan upgrade Free products Whatever The point here is that keeping old code around costs money. And that’s money better spend at making your customer happy than your developers unhappy. Lastly we can remove the typo field from the API. Making the code lean and both customers and developers happy. “Email Notification” by cathy moser from the Noun Project: https://thenounproject.com/term/email-notification/896369/ “Magnifying Glass” by Nicole Macdonald from the Noun Project: https://thenounproject.com/term/magnifying-glass/160554/ “Time” by BomSymbols from the Noun Project: https://thenounproject.com/term/time/526522/ “Carrot” by Creative Stall from the Noun Project: https://thenounproject.com/term/carrot/105128/ “Celebration” by Llisole from the Noun Project: https://thenounproject.com/term/celebration/1030170/
- #37: You can reach me on: Twitter E-mail Slack. Join the HTTP API slack! It's full of great people in love with the web and APIs.