Versioning

Definition

Versioning coverage in this archive spans 3 posts from May 2017 to Mar 2022 and deals with structural tradeoffs: coupling, failure boundaries, and long-term change cost. The strongest adjacent threads are api, rest, and architecture. Recurring title motifs include api, versioning, pick, and stop.

Key claims

Most pieces recommend choosing the simplest architecture that can be operated confidently.
The consistent theme from 2017 to 2022 is disciplined execution over hype cycles.
This topic repeatedly intersects with api, rest, and architecture, so design choices here rarely stand alone.

Practical checklist

Define failure domains and data boundaries before introducing additional services or protocols.
Start with the newest post to calibrate current constraints, then backtrack to older entries for first principles.
When boundary questions appear, cross-read api and rest before committing implementation details.

Failure modes

Breaking systems into many parts without clear ownership of cross-service behavior.
Choosing architecture for trend alignment rather than workload constraints.
Applying guidance from 2017 to 2022 without revisiting assumptions as context changed.

References

API Versioning: Pick One and Stop Overthinking It

Mar 2022

API versioning is a maintenance commitment, not a design exercise. URL paths win for public APIs, headers for internal ones. The real discipline is not versioning -- it's avoiding breaking changes in the first place.

I Tried Every API Versioning Strategy. Here's the One I Actually Use.

Feb 2020

After dealing with versioning messes at multiple companies, I landed on URL path versioning for anything public. Here's why the alternatives didn't survive contact with reality.

API Versioning: What Actually Works and What Doesn't

May 2017

We tried multiple API versioning approaches at the fintech startup. URL path versioning won. Here's why, plus how to handle deprecation without burning your consumers.