API Versioning for Solo Founders: URI vs Header, and How to Deprecate Without Drowning

Why Versioning Is a Founder Problem If you are a one-person team, versioning feels like overhead. You control the frontend and the backend, so why not change both at once. That works until a paying customer writes an integration. Or until your customers need a stable contract. Or until an MCP caller pins to whatever version you shipped on day one. Speakeasy warns that breaking changes after integration can disrupt clients and drive churn. The reason is simple. Even a tiny change forces the consumer to schedule time to adapt. Your version number is really a promise about which contract is live. The Three Real Options Most guides list four or five versioning styles. For a small team, you are choosing between three. First, URI path versioning, like slash v1 slash users. It gives maximum visibility, trivial gateway routing, friendly HTTP caching, and easy log grepping. The downside is parallel route trees can drift. Second, header versioning, with Accept application slash vnd dot yourapi dot v2 plus json. Redocly notes it keeps URLs clean and aligns with REST, but hurts discoverability and complicates caching. Third, query parameter versioning, like question mark version equals 2. It is flexible but worst for caching and log clarity. A Decision Rule for One Engineer Use this checklist before you write your first route. If you ship a public API and do not know who will call it, choose URI path versioning. Visibility compounds over years. If your API is a thin MCP surface and you control every caller, skip versions entirely and add new endpoints instead. That is the evolution strategy Redocly describes. If the API is internal only, skip formal versioning until a second consumer appears. If your gateway already pushes you toward header versioning, stay with it. Switching to win a style argument is wasted founder time. What Deprecation Actually Requires A deprecation is not a blog post. It is a multi-step operation. First, write a sunset date into the response header. Second, tell humans in three places: email, docs banner, community channel. Third, log who still hits the old version. Redocly calls this out directly. Without per-route metrics you decide blind. Fourth, run a quiet period of at least one full release cycle. Fifth, move to warning only as sunset nears. Hard kills on a Friday lose accounts. Sixth, sunset with a 410 Gone and a migration link. Budget three to six months for B2B. Keeping Multiple Versions Alive Cheaply Every additional version increases surface area. Redocly states this plainly and warns teams underestimate the long-term cost. Three habits keep that cost in check. Share the business logic and branch only at the edge. Version selection happens in a thin router that picks a serializer, not in duplicated controllers. Version the contract, not the code, by generating serializers from an OpenAPI or JSON Schema spec. Drift becomes a build error instead of a support ticket. Cap the number of live versions to two, current and previous. Refusals to migrate become sales conversations, not engineering ones. A Practical First-Time Setup If you ship your first public endpoint this week, here is the minimal setup. Pick URI path versioning and route slash v1 star to a router. Generate an OpenAPI file for slash v1 from your code, or your code from the spec. Add structured logging that includes the route template, not just the URL. Add a Deprecation and Sunset header convention to your gateway now, before you need it. Write a one-page deprecation policy with date format, contact channel, and minimum notice. Paste it into your docs before it matters. Full sources and the original guide are linked in the description.