API versioning strategy
Managing breaking changes while maintaining backward compatibility.
Every API grows, and every growth breaks something. This template maps the decision gate where you decide whether to increment the version: non-breaking changes stay on the same major version, but the moment you remove a field or restructure a response, you create a new major version that coexists with the old one until clients migrate over.
The critical insight is the parallel deployment. You do not shut down v1 the day v2 ships. You run both, you tell clients the old one is deprecated, you give them a deadline, and you track who has actually migrated. Only then do you delete the infrastructure.
When to use this template
- API design phase — before you accept a breaking change, walk the team through this flow so everyone sees: we will support two versions in production, we will alert customers, we will wait 12 months, then we cut it off. Knowing the true cost upfront changes the decision.
- Deprecation communications — show this diagram in your blog post or email announcement so clients understand the timeline and what happens if they don't migrate.
- Infrastructure planning — use the parallel deployment and cutoff nodes to budget the operational cost and to calendar the decommissioning.
How to adapt it
Rename the versions to match your scheme (v1/v2, major.minor, or commit hash) and set your own timeline:
- Replace the "12-month" deadline with your real policy — some teams do 6 months, others 24.
- Insert a gateway pattern node after "Deploy v1 & v2" if your load balancer routes based on header or parameter.
- Add a migration guide link on the notification node so clients see documentation, not just a deprecation notice.
Visual edits regenerate clean code, so you can adapt the timeline and add your company's specific deprecation process without touching Mermaid syntax.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
flowchart TD
A[New API change required] --> B{Breaking change?}
B -->|No| C[Increment patch/minor]
C --> D[Deploy to production]
D --> E[Clients use new version]
B -->|Yes| F[Create new major version]
F --> G[Deploy v1 & v2 in parallel]
G --> H[Notify clients of deprecation]
H --> I{Clients migrated?}
I -->|No, wait| J[Set deadline reminder]
J --> I
I -->|Yes| K[Disable old version]
K --> L[Remove from infrastructure]
Frequently asked questions
- What is API versioning and why do I need it?
- API versioning lets you evolve your service without breaking existing clients. When you remove a field or change a response structure, old clients that depend on it break unless they can opt into a newer version. This diagram shows the decision: non-breaking changes stay on the same major version; breaking changes create a new major version that coexists with the old one until clients migrate.
- What's the difference between URL versioning, header versioning, and content negotiation?
- URL versioning (/v1/users, /v2/users) is most explicit — clients see the version in the path. Header versioning (Accept: application/vnd.api+json;version=2) is less visible but doesn't clutter URLs. Content negotiation (same URL, version in Accept header) is elegant but harder for clients to discover. This diagram applies to all three; the strategy is the same, only the mechanism changes.
- How long should I keep an old API version alive?
- Industry standard is 12–18 months from the deprecation date. Set a deadline, announce it in release notes and emails, and enforce the cutoff. Keeping old versions forever increases infrastructure costs and security surface. Showing the deadline in this diagram forces the whole team to commit upfront to when the old version actually dies.
- How do I handle clients that never migrate to the new version?
- Send one final notice 30 days before cutoff. On cutoff day, return 410 Gone or 426 Upgrade Required so clients get a clear error rather than silent data corruption. Log which old-client IPs tried to use the deprecated version after cutoff — often a small tail of clients that are truly orphaned and can be contacted directly or tolerated as a known risk.