It is interesting to have studied API versioning all of these years. Every conference I produced and supported, the discussions around API versioning are always the most attended, heated, and engaging. Engineers hold very strong opinions about how to version, what involves version, and when to version, as well as why you shouldn’t version at all. It is a fascinating discourse. However, when you actually tune into the change logs of top API platforms you realize that most aren’t as religious about managing change as the discourse would leave you to believe, and breaking changes, lack of communication, and other problems are actually pretty commonplace. As with many other isolated technological concerns in the API space, this reality has me zooming out to see what might be actually driving this from the business or political dimensions.
- Business Deadlines - It feels like version control is a response to unrealistic business deadlines perpetually imposed on engineers.
- Lack of Control - As engineers we don’t have a lot of control over the overall direction of our work, and getting pedantic here helps.
- Blaming - Breaking changes seem to be less about the damage caused and just being able to point somewhere and shift the blame.
- Perpetual Change - Things never stop and being able to apply a semantic version or date version positions us within the machine.
- Resisting Velocity - Versioning is our way of resisting the velocity of the enterprise that is out of our control helping us stay sane.
In the end API versioning feels like theater. I mean, most API operations are just theater, but I feel like versioning takes center stage as a reaction from engineering towards business over it being about managing and communicating change. I have seen first hand how little control we have over the direction of enterprise technology in engineering groups. I know we like to think we are wizards and drive everything, which we may in some enterprises, but I think the status quo is quite the opposite in many mainstream enterprises. I think that most teams producing APIs are just responding to unrealistic business deadlines, strategy shifts, and musical chairs randomly shuffling priorities. I feel like we are just drawing little chalk lines on the sidewalk as V1 and V2 or 2025-03-21 to respond to a lot of things that are out of control, and occasionally we might play a game of hopscotch with our chalk lines to show we are doing something, but rarely is it doing what we claim it is doing.
