Successful API Transitions: Python 3 Migration and Zulip Case Study
This content outlines the challenges and successes of API transitions through two case studies: the Python 3 migration and the Zulip API evolution. It discusses the importance of smooth transitions for individual implementations and ecosystems, sharing lessons learned and techniques used to facilitate the process. The Python 3 migration journey, starting from its development to the challenges faced in adoption, is showcased along with the Zulip API's evolution, emphasizing the need for backwards and forwards compatibility. The toolbox of techniques developed for these transitions is highlighted, offering insights on minimizing burdens and efforts for staying current with API versions.
Download Presentation
Please find below an Image/Link to download the presentation.
The content on the website is provided AS IS for your information and personal use only. It may not be sold, licensed, or shared on other websites without obtaining consent from the author. If you encounter any issues during the download, it is possible that the publisher has removed the file from their server.
You are allowed to download the files provided on this website for personal or commercial use, subject to the condition that they are used lawfully. All files are the property of their respective owners.
The content on the website is provided AS IS for your information and personal use only. It may not be sold, licensed, or shared on other websites without obtaining consent from the author.
E N D
Presentation Transcript
API transition toolboxes Tim Abbott
Agenda: API Transition Toolboxes - - - - The Dream: Consistently successful API transitions Case study: Python 3.0 and 3.x Case study: Zulip Vision: An API transitions toolbox for FHIR
Dream: Consistently successful API transitions For an individual implementation: - - New versions come with a lot of benefit Benefits are locked behind upgrading - Web of partners can limit unilateral upgrades For the ecosystem: - - Freedom to make improvements (judiciously!) Future users greatly outnumber current ones
Case study: The Python 3 nightmare - - - - - March 2006: Python 3 development begins December 2008: Python 3.0 released. Hurray!!!??? December 2016: Python 2.6/2.7 remain 85% of downloads. October 2019: 50% of new Python downloads are Python 2. January 2020: Python 2.7 desupported. Migration required a change in strategy
Lessons from the Python 3 migration - Breaking transitions are very challenging for an ecosystem - Realistic for a script run 2to3 and cut over . - Unrealistic for libraries: web of dependencies. Developed a toolbox of techniques - Tool: Compatibility library (six) - Tool: Linters and automatic code upgrader tools - Tool: Multi-release transitions can replace breaking transitions Toolbox allowed the Python 3 transition to complete. Toolbox makes modern Python 3.x transitions a breeze. - - -
Case study: The Zulip API - - - - Zulip is organized team chat (competes with Slack/Teams) Self-hosted (~2 major releases/year) and Cloud (weekly) Single API shared by all clients (web, desktop, mobile, terminal) Backwards-compatibility and forwards-compatibility - Servers don t always upgrade. - Clients don t always upgrade.
The Zulip API transitions toolbox - Originally, lots of ad-hoc design/communication - Made us reluctant to make changes Built a toolbox of techniques - Hundreds of API transitions (~100/year) - Easy enough that we fix minor mistakes. Next: Examples from our toolbox Pay attention to the goals / design philosophy - Minimize burden/effort for staying current - - -
Tool: Every change is backwards-compatible - - Rename something: Accept either, send both Reformat a data structure: Send both old and new formats - (If large, include option to only send newer format.) Example: Rename realm_uri to realm_url -
Tool: Granular API changelog with feature levels Alternative schemes: - Unsorted numbers (XMPP s XEPs) - Release date (Stripe) - Named capabilities - Separate buckets for different API groups (Kubernetes)
Impact of this API transition toolbox on Zulip - - - - Communication through API documentation itself Better code, both in server and client implementations Interoperability bugs are rare Freedom to correct mistakes
Vision: An API transitions toolbox for FHIR - If you want a vibrant open-source community, you should relentlessly debug and optimize the new contributor experience like you would any other product. (My advice to OSS projects hoping to build a community) - If you want an API to thrive, you should relentlessly debug and optimize the experience of upgrading to newer versions like you would any other product.
