Git Branching Strategy: Trunk-Based vs GitFlow for Teams
Trunk-based development or GitFlow? Compare Git branching strategies for outsourced and offshore teams, with a decision table and rules that keep releases safe.
How to version and retire APIs without breaking clients: versioning options, breaking-change rules, sunset policies and a checklist for outsourced teams.
Sooner or later every successful API has to change. A field gets renamed, a response shape turns out to be wrong, a pricing model needs a new object. The trouble is that you rarely control every client. Mobile apps stay on old versions for months, partners integrate once and forget, and customers write scripts you never hear about. A clear API versioning and deprecation strategy is what lets you keep improving the product without causing outages for the people who depend on it.
This guide is written for CTOs, founders and product managers who commission APIs, whether in-house or with an outsourced team, and want change to be boring rather than risky.
The cheapest version bump is the one you never make. Most changes can be made additively, and additive changes do not require a new version:
Put one rule in your API guidelines and in your contract with any development partner: clients must ignore fields they do not recognise. Without it, even additive changes can break strict parsers.
Agree on a written definition. A change is breaking if a correctly written existing client could fail after it. Typical examples:
Meaning changes are the most dangerous because nothing looks different in the schema. Review them as seriously as removals.
| Approach | Example | Strengths | Trade-offs |
|---|---|---|---|
| URI path | /v2/orders |
Obvious, easy to route, easy to test in a browser | Version spreads across every resource; encourages large version jumps |
| Custom header | API-Version: 2026-11-01 |
Clean URLs; supports date-based versions | Less visible; harder to try manually; caches must vary on the header |
| Media type | Accept: application/vnd.example.v2+json |
Fits REST purists’ view of representations | Awkward tooling and documentation |
| Query parameter | /orders?version=2 |
Simple to add | Easy to forget; can pollute caching and logs |
For most products, URI path versioning is the pragmatic choice. It is easy for partners and mobile developers to understand and straightforward to document. Date-based header versioning can work very well for mature public APIs, but it needs more discipline and tooling. Whichever you pick, choose it once and apply it consistently. Mixed schemes are a common source of confusion in inherited codebases.
Version the contract, not every deployment. A major version should change rarely, perhaps every year or two, and should bundle several breaking changes together so clients migrate once.
A deprecation policy is a promise, so write it down and publish it:
Sunset HTTP header (defined in RFC 8594) with the removal date, and a Deprecation header or a link to migration notes, so developers see warnings in their own logs.Web clients update the moment you deploy. Mobile clients do not. An app released a year ago may still be in use, so an API removal can break real users with no way to hotfix them. Plan for this by combining version support windows with a force-update mechanism, which we cover in our guide to mobile app force update and API compatibility. Track the share of traffic per app version and retire an API version only when that traffic is genuinely negligible.
Versioning rules that live only in a wiki will be broken under deadline pressure. Automate them:
Every supported version is code to maintain, secure and test. Avoid copying whole codebases per version. Instead, keep one core domain model and translate at the edge, with thin adapters converting between the current model and each older response format. Track how many versions are live and put sunset dates in the backlog so that old versions actually get removed.
Sunset header and changelog entries for every deprecationIf you outsource backend work, put these rules into the statement of work so they are acceptance criteria rather than good intentions. Our guide to REST API design best practices covers the wider design decisions that make versioning easier.
AkMo Technologies designs, builds and maintains APIs for web and mobile products. Learn more about our web development services, or contact us to discuss an API you are planning or need to evolve safely.
Trunk-based development or GitFlow? Compare Git branching strategies for outsourced and offshore teams, with a decision table and rules that keep releases safe.
Monorepo or polyrepo? Compare code repository strategies for web, mobile and backend products, with a decision table and tips for outsourced teams.
A practical webhooks guide for product teams: how webhooks work, signature verification, retries, idempotency and monitoring for reliable integrations.
Tell us about your platform, your product idea or the systems you want to modernise. Someone from our Chennai engineering team will get back to you personally.