apidays New York 2025 - Two tales of API Change Management by Eric Koleda (Coda)

Two tales of API Change Management from my time at Google
Eric Koleda, Developer Advocate at Coda

apidays New York 2025
API Management for Surfing the Next Innovation Waves: GenAI and Open Banking
May 14 & 15, 2025

------

Check out our conferences at https://www.apidays.global/

Do you want to sponsor or talk at one of our conferences?
https://apidays.typeform.com/to/ILJeAaV8

Learn more on APIscene, the global media made by the community for the community:
https://www.apiscene.io

Explore the API ecosystem with the API Landscape:
https://apilandscape.apiscene.io/

Transcript

1. A Tale of Two APIs Lesson s on API chan ge m an agem en t fr om m y tim e at Google by Eric Koleda
2. Two takeaways 1. Never m ake br eakin g chan ges 2. Con stan tly m ake br eakin g chan ges
3. A little about m e • 16 years in Developer Relations roles • Worked at Google, Coda, and now Grammarly • Focus on productivity products and integration use cases • Collaborated with dozens of API teams
4. Ch an ge is in evitable Evolution of the un der lyin g pr oduct featur e set • "Projects can now have multiple owners" • "Comments can no longer have attachments" Refactor in g of the in ter n al ar chitectur e • "Webhooks need to be pre-registered" • "We're moving to JSON-RPC" Adaptin g to the n eeds of the developer com m un ity • "That endpoint now supports the IDs shown in the UI" • "We're adding streaming support for LLMs"
5. Design in g for ch an ge Build in ter faces that ar e flexible • Use objects instead of primitive types, to allow for new fields to be added • Break functionality into a granular set of endpoints (ex: /contact/{id}/addresses) But all design s have em bedded assum ption s • If relationships are one-to-one, one-to-many, or many-to-many • The hierarchy of different entities (ex: tasks belong to projects) Tr adeoffs between flexibility an d sim plicity • Making it easier to extend in the future may make it more difficult to use in the present • Let's look at an example →
8. Wh at do you pr ior itize? Existin g developer s or n ew developer s? • Continuing to use outdated terminology • Requiring extra parameters to get the new behavior Exter n al stability or in ter n al velocity? • Designing your API around your org chart • API sprawl vs managed growth
9. My Exper ien ce with Two APIs
10. Let's m eet our ch ar acter s AdWor ds API • AdWords allows advertisers to run ads on Google.com and other properties • API was aimed at very large companies that need to automate bidding • SOAP API with tons of complexity with contributions from many dev teams Apps Scr ipt • Allows Google Workspace users to create scripts and macros (like VBA) • Primarily used by "spreadsheet wizards" that want to automate their work • Hosted JavaScript runtime with built-in libraries for Google products
11. Adwor ds API "H am ster wh eel" • New version released approximately every 4 months • Only the newest three versions supported • Required developers to do 1-2 migrations per-year • Breaking changes could be introduced in any release • Lots of effort required to communicate, educate, and validate developers on each new release
12. Apps Scr ipt "Fr ozen in am ber " • The core libraries have no versioning, no releases • All changes are additive, with (almost) no breaking changes • Difficult engineering and design challenges when preserving backwards compatibility
13. Wh y did th e sam e com pan y h ave such r adically differ en t appr oach es?
14. Audien ce Who are the developers that used the API? AdWor ds API • Professional developers at large organizations • Familiar with software development best practices • Consistent engagement with the codebase Apps Scr ipt • "Citizen developers", who's main job was not programming • Often wrote throw-away, spaghetti code • No one paying attention to the code, no institutional knowledge
15. Relation ship What does our relationship with those developers look like? AdWor ds API • Customers had strong business need behind the integration • Captive developer audience, as there was no alternative to using the API • Customer and partner managers maintained direct lines of communication Apps Scr ipt • Integrations were usually additive (automate some small task) and not business-critical • Lots of competing products for automation in the marketplace • No clear point-of-contact for a given integration, relied on broadcast channels (blog, etc)
16. Goals What do we get out of the relationship? AdWor ds API • Lots of spend passed through the API, important to the core business • Important that developer expose new product features to their users • New features aimed at boosting click through rate (CTR) and therefore revenue Apps Scr ipt • Integrations aimed at increasing customer happiness and stickiness • Important that automations and workflows keep running smoothly • Harder to churn to a competitor when lots of scripts power your business
17. Wh at does th is m ean for your APIs? Not a playbook • These two APIs took extreme approaches that likely don't translate to many other scenarios • Each approach required a fair amount of effort Br oaden your hor izon s • There is wide spectrum of options in front of you • You don't have to follow the same pattern as everyone else
18. Two Th r ee takeaways 1. Some APIs n ever m ake br eakin g chan ges 2. Some APIs con stan tly m ake br eakin g chan ges 3. You should do what m akes sen se for your audien ce, r elation ships, an d goals
19. Than k you! lin kedin .com / in / ekoleda twitter .com / er ickoleda erickoleda.bsky.social