Files
skills/public/api-api-versioning.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

606 lines
30 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>api-api-versioning</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/api-api-versioning.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/api-api-versioning">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/api-api-versioning.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>api-api-versioning</h1><p class="lede">Planning API changes and deciding on versioning approach</p><h1>API Versioning</h1>
<p><strong>Scope</strong>: API versioning strategies, breaking changes, deprecation workflow, migration patterns <strong>Lines</strong>: ~200 <strong>Last Updated</strong>: 2025-10-18</p>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Planning API changes and deciding on versioning approach</li><li>Managing multiple API versions in production</li><li>Deprecating old API versions</li><li>Migrating clients to new API versions</li><li>Designing backward compatibility strategies</li><li>Implementing breaking changes safely</li><li>Establishing sunset policies for legacy APIs</li></ul>
<h2>Core Concepts</h2>
<h3>What is API Versioning?</h3>
<p><strong>Problem</strong>: APIs evolve over time. Changes can break existing clients.</p>
<p><strong>Solution</strong>: Maintain multiple API versions simultaneously, allowing clients to migrate gradually.</p>
<p><strong>Benefits</strong>:</p>
<ul><li>Backward compatibility for existing clients</li><li>Safe deployment of breaking changes</li><li>Gradual client migration</li><li>Clear contract between API and clients</li></ul>
<p><strong>Cost</strong>:</p>
<ul><li>Maintenance burden (multiple codebases)</li><li>Testing complexity</li><li>Documentation overhead</li></ul>
<hr>
<h2>Versioning Strategies</h2>
<h3>1. URL Path Versioning</h3>
<p><strong>Format</strong>: <code>/v1/users</code>, <code>/v2/users</code></p>
<p><strong>Example</strong>:</p>
<pre><code>GET /v1/users/123
GET /v2/users/123</code></pre>
<p><strong>Implementation</strong> (FastAPI):</p>
<pre><code class="lang-python">from fastapi import FastAPI
app = FastAPI()
# Version 1
@app.get(&quot;/v1/users/{user_id}&quot;)
async def get_user_v1(user_id: int):
return {&quot;id&quot;: user_id, &quot;name&quot;: &quot;Alice&quot;}
# Version 2 (with email field)
@app.get(&quot;/v2/users/{user_id}&quot;)
async def get_user_v2(user_id: int):
return {
&quot;id&quot;: user_id,
&quot;name&quot;: &quot;Alice&quot;,
&quot;email&quot;: &quot;[email protected]&quot;
}</code></pre>
<p><strong>Pros</strong>:</p>
<ul><li>Simple and explicit</li><li>Easy to route and cache</li><li>Visible in logs and monitoring</li><li>Works with all HTTP clients</li></ul>
<p><strong>Cons</strong>:</p>
<ul><li>URL changes break bookmarks</li><li>Version in URL feels unnatural</li><li>No granular versioning per endpoint</li></ul>
<p><strong>Best for</strong>: Public APIs, REST APIs, simple versioning schemes</p>
<hr>
<h3>2. Header Versioning</h3>
<p><strong>Format</strong>: <code>Accept: application/vnd.api.v1+json</code></p>
<p><strong>Example</strong>:</p>
<pre><code class="lang-http">GET /users/123
Accept: application/vnd.api.v2+json</code></pre>
<p><strong>Implementation</strong> (FastAPI):</p>
<pre><code class="lang-python">from fastapi import FastAPI, Header, HTTPException
app = FastAPI()
@app.get(&quot;/users/{user_id}&quot;)
async def get_user(
user_id: int,
accept: str = Header(default=&quot;application/vnd.api.v1+json&quot;)
):
if &quot;v2&quot; in accept:
return {
&quot;id&quot;: user_id,
&quot;name&quot;: &quot;Alice&quot;,
&quot;email&quot;: &quot;[email protected]&quot;
}
elif &quot;v1&quot; in accept:
return {&quot;id&quot;: user_id, &quot;name&quot;: &quot;Alice&quot;}
else:
raise HTTPException(400, &quot;Unsupported API version&quot;)</code></pre>
<p><strong>Pros</strong>:</p>
<ul><li>Clean URLs (no version pollution)</li><li>RESTful (resource unchanged, representation varies)</li><li>Granular control per request</li></ul>
<p><strong>Cons</strong>:</p>
<ul><li>Less discoverable (hidden in headers)</li><li>Harder to test (need header support)</li><li>Caching complexity</li></ul>
<p><strong>Best for</strong>: Internal APIs, strict REST adherence, content negotiation</p>
<hr>
<h3>3. Query Parameter Versioning</h3>
<p><strong>Format</strong>: <code>/users?api_version=2</code></p>
<p><strong>Example</strong>:</p>
<pre><code>GET /users/123?api_version=2</code></pre>
<p><strong>Implementation</strong> (FastAPI):</p>
<pre><code class="lang-python">from fastapi import FastAPI, Query
app = FastAPI()
@app.get(&quot;/users/{user_id}&quot;)
async def get_user(
user_id: int,
api_version: int = Query(default=1)
):
if api_version == 2:
return {
&quot;id&quot;: user_id,
&quot;name&quot;: &quot;Alice&quot;,
&quot;email&quot;: &quot;[email protected]&quot;
}
else:
return {&quot;id&quot;: user_id, &quot;name&quot;: &quot;Alice&quot;}</code></pre>
<p><strong>Pros</strong>:</p>
<ul><li>Simple to implement</li><li>Easy to test (just add parameter)</li><li>Works with all clients</li></ul>
<p><strong>Cons</strong>:</p>
<ul><li>Version in query string feels unnatural</li><li>Pollutes URL space</li><li>Can conflict with other parameters</li></ul>
<p><strong>Best for</strong>: Simple internal APIs, quick prototypes</p>
<hr>
<h3>4. Custom Header Versioning</h3>
<p><strong>Format</strong>: <code>X-API-Version: 2</code></p>
<p><strong>Example</strong>:</p>
<pre><code class="lang-http">GET /users/123
X-API-Version: 2</code></pre>
<p><strong>Implementation</strong> (FastAPI):</p>
<pre><code class="lang-python">from fastapi import FastAPI, Header
app = FastAPI()
@app.get(&quot;/users/{user_id}&quot;)
async def get_user(
user_id: int,
x_api_version: int = Header(default=1)
):
if x_api_version == 2:
return {
&quot;id&quot;: user_id,
&quot;name&quot;: &quot;Alice&quot;,
&quot;email&quot;: &quot;[email protected]&quot;
}
else:
return {&quot;id&quot;: user_id, &quot;name&quot;: &quot;Alice&quot;}</code></pre>
<p><strong>Pros</strong>:</p>
<ul><li>Clean URLs</li><li>Explicit versioning</li><li>Easy to add middleware</li></ul>
<p><strong>Cons</strong>:</p>
<ul><li>Custom headers not standard</li><li>Requires client header support</li><li>Less discoverable</li></ul>
<p><strong>Best for</strong>: Internal APIs, microservices, controlled environments</p>
<hr>
<h2>Breaking vs Non-Breaking Changes</h2>
<h3>Non-Breaking Changes (Safe)</h3>
<p><strong>Can deploy without versioning</strong>:</p>
<p>✅ <strong>Adding optional fields to request</strong>:</p>
<pre><code class="lang-json">// Before
{&quot;name&quot;: &quot;Alice&quot;}
// After (optional email)
{&quot;name&quot;: &quot;Alice&quot;, &quot;email&quot;: &quot;[email protected]&quot;}</code></pre>
<p>✅ <strong>Adding new fields to response</strong>:</p>
<pre><code class="lang-json">// Before
{&quot;id&quot;: 1, &quot;name&quot;: &quot;Alice&quot;}
// After (added email)
{&quot;id&quot;: 1, &quot;name&quot;: &quot;Alice&quot;, &quot;email&quot;: &quot;[email protected]&quot;}</code></pre>
<p>✅ <strong>Adding new endpoints</strong>:</p>
<pre><code>POST /v1/users (existing)
POST /v1/users/bulk (new, safe)</code></pre>
<p>✅ <strong>Adding new optional query parameters</strong> ✅ <strong>Expanding enum values</strong> (if clients ignore unknown) ✅ <strong>Relaxing validation</strong> (accepting more input)</p>
<hr>
<h3>Breaking Changes (Require Versioning)</h3>
<p><strong>Must introduce new version</strong>:</p>
<p>❌ <strong>Removing fields from response</strong>:</p>
<pre><code class="lang-json">// Before
{&quot;id&quot;: 1, &quot;name&quot;: &quot;Alice&quot;, &quot;email&quot;: &quot;[email protected]&quot;}
// After (removed email) - BREAKS CLIENTS
{&quot;id&quot;: 1, &quot;name&quot;: &quot;Alice&quot;}</code></pre>
<p>❌ <strong>Renaming fields</strong>:</p>
<pre><code class="lang-json">// Before
{&quot;user_id&quot;: 1}
// After - BREAKS CLIENTS
{&quot;id&quot;: 1}</code></pre>
<p>❌ <strong>Changing field types</strong>:</p>
<pre><code class="lang-json">// Before
{&quot;created_at&quot;: &quot;2025-01-15&quot;}
// After - BREAKS CLIENTS
{&quot;created_at&quot;: 1736899200}</code></pre>
<p>❌ <strong>Making optional field required</strong> ❌ <strong>Removing endpoints</strong> ❌ <strong>Changing URL structure</strong> ❌ <strong>Stricter validation</strong> (rejecting previously valid input) ❌ <strong>Changing authentication scheme</strong></p>
<hr>
<h2>Breaking Change Checklist</h2>
<p>Before introducing breaking change:</p>
<pre><code>[ ] Identified all affected clients
[ ] Planned new version number/identifier
[ ] Implemented both old and new versions
[ ] Created migration guide for clients
[ ] Set deprecation timeline (e.g., 6 months)
[ ] Added deprecation warnings to old version
[ ] Updated documentation
[ ] Communicated timeline to stakeholders
[ ] Monitored usage of old version
[ ] Planned sunset date for old version</code></pre>
<hr>
<h2>Deprecation Workflow</h2>
<h3>Phase 1: Announce (Month 0)</h3>
<p><strong>Actions</strong>:</p>
<ol><li>Document breaking changes</li><li>Announce deprecation timeline</li><li>Add deprecation headers to old version</li></ol>
<p><strong>Example</strong> (FastAPI):</p>
<pre><code class="lang-python">from fastapi import Response
@app.get(&quot;/v1/users/{user_id}&quot;)
async def get_user_v1(user_id: int, response: Response):
# Add deprecation warning
response.headers[&quot;Deprecation&quot;] = &quot;true&quot;
response.headers[&quot;Sunset&quot;] = &quot;2025-07-01&quot;
response.headers[&quot;Link&quot;] = &#x27;&lt;/v2/users&gt;; rel=&quot;successor-version&quot;&#x27;
return {&quot;id&quot;: user_id, &quot;name&quot;: &quot;Alice&quot;}</code></pre>
<p><strong>Communication</strong>:</p>
<pre><code>Subject: API v1 Deprecation Notice
We&#x27;re deprecating /v1/users in favor of /v2/users.
Timeline:
- Today: v2 available, v1 still supported
- Month 3: Deprecation warnings added to v1
- Month 6: v1 sunset (will return 410 Gone)
Migration guide: https://docs.api.com/v1-to-v2
Questions? Contact [email protected]</code></pre>
<hr>
<h3>Phase 2: Warn (Month 3)</h3>
<p><strong>Actions</strong>:</p>
<ol><li>Log clients still using old version</li><li>Send targeted emails to heavy users</li><li>Add warning in response body</li></ol>
<p><strong>Example</strong>:</p>
<pre><code class="lang-python">@app.get(&quot;/v1/users/{user_id}&quot;)
async def get_user_v1(user_id: int, response: Response):
response.headers[&quot;X-Deprecation-Warning&quot;] = &quot;v1 will sunset on 2025-07-01&quot;
return {
&quot;id&quot;: user_id,
&quot;name&quot;: &quot;Alice&quot;,
&quot;_deprecation&quot;: {
&quot;message&quot;: &quot;This endpoint will be removed on 2025-07-01&quot;,
&quot;migration_guide&quot;: &quot;https://docs.api.com/v1-to-v2&quot;
}
}</code></pre>
<hr>
<h3>Phase 3: Sunset (Month 6)</h3>
<p><strong>Actions</strong>:</p>
<ol><li>Return <code>410 Gone</code> for old version</li><li>Redirect to migration guide</li><li>Monitor for stragglers</li></ol>
<p><strong>Example</strong>:</p>
<pre><code class="lang-python">@app.get(&quot;/v1/users/{user_id}&quot;)
async def get_user_v1(user_id: int):
raise HTTPException(
status_code=410,
detail={
&quot;error&quot;: &quot;This API version has been sunset&quot;,
&quot;sunset_date&quot;: &quot;2025-07-01&quot;,
&quot;migration_guide&quot;: &quot;https://docs.api.com/v1-to-v2&quot;,
&quot;new_endpoint&quot;: &quot;/v2/users/{user_id}&quot;
}
)</code></pre>
<hr>
<h2>Deprecation Timeline Template</h2>
<pre><code>Month 0: Announcement
- Release v2 alongside v1
- Announce deprecation timeline
- Update documentation
Month 1-2: Migration Period
- Monitor v1 usage
- Provide migration support
- Send reminder emails
Month 3: Warning Phase
- Add deprecation headers
- Log clients using v1
- Contact heavy users directly
Month 4-5: Final Warning
- Increase warning visibility
- Offer migration assistance
- Set hard sunset date
Month 6: Sunset
- Return 410 Gone for v1
- Redirect to migration guide
- Monitor for issues</code></pre>
<p><strong>Adjust timeline based on</strong>:</p>
<ul><li>API criticality (longer for critical APIs)</li><li>Number of clients (longer for many clients)</li><li>Migration complexity (longer for complex changes)</li></ul>
<p><strong>Recommended timelines</strong>:</p>
<ul><li>Internal APIs: 3 months</li><li>Public APIs: 6-12 months</li><li>Critical APIs: 12-24 months</li></ul>
<hr>
<h2>Version Migration Patterns</h2>
<h3>Pattern 1: Parallel Versions</h3>
<p><strong>Strategy</strong>: Run old and new versions side-by-side.</p>
<pre><code class="lang-python"># v1/users.py
@router.get(&quot;/v1/users/{user_id}&quot;)
async def get_user_v1(user_id: int):
return {&quot;id&quot;: user_id, &quot;name&quot;: &quot;Alice&quot;}
# v2/users.py
@router.get(&quot;/v2/users/{user_id}&quot;)
async def get_user_v2(user_id: int):
return {
&quot;id&quot;: user_id,
&quot;name&quot;: &quot;Alice&quot;,
&quot;email&quot;: &quot;[email protected]&quot;
}</code></pre>
<p><strong>Pros</strong>: Clean separation, easy rollback <strong>Cons</strong>: Code duplication, maintenance burden</p>
<hr>
<h3>Pattern 2: Adapter Pattern</h3>
<p><strong>Strategy</strong>: Single core implementation, adapters for each version.</p>
<pre><code class="lang-python"># core/users.py
def get_user_data(user_id: int):
return {
&quot;id&quot;: user_id,
&quot;name&quot;: &quot;Alice&quot;,
&quot;email&quot;: &quot;[email protected]&quot;
}
# api/v1.py
@app.get(&quot;/v1/users/{user_id}&quot;)
async def get_user_v1(user_id: int):
data = get_user_data(user_id)
# Adapter: remove email for v1
return {&quot;id&quot;: data[&quot;id&quot;], &quot;name&quot;: data[&quot;name&quot;]}
# api/v2.py
@app.get(&quot;/v2/users/{user_id}&quot;)
async def get_user_v2(user_id: int):
return get_user_data(user_id) # Full data</code></pre>
<p><strong>Pros</strong>: Single source of truth, less duplication <strong>Cons</strong>: Adapter complexity increases over time</p>
<hr>
<h3>Pattern 3: Feature Flags</h3>
<p><strong>Strategy</strong>: Use flags to toggle new behavior.</p>
<pre><code class="lang-python">from functools import wraps
def version_aware(func):
@wraps(func)
async def wrapper(user_id: int, version: int = 1):
data = await func(user_id)
if version == 1:
# Remove new fields for v1
return {k: v for k, v in data.items() if k in [&quot;id&quot;, &quot;name&quot;]}
else:
return data
return wrapper
@version_aware
async def get_user(user_id: int):
return {
&quot;id&quot;: user_id,
&quot;name&quot;: &quot;Alice&quot;,
&quot;email&quot;: &quot;[email protected]&quot;
}</code></pre>
<p><strong>Pros</strong>: Single endpoint, flexible <strong>Cons</strong>: Complexity in logic, harder to test</p>
<hr>
<h2>Backward Compatibility Techniques</h2>
<h3>Technique 1: Additive Changes Only</h3>
<p><strong>Rule</strong>: Only add, never remove or change.</p>
<pre><code class="lang-json">// Version 1
{&quot;id&quot;: 1, &quot;name&quot;: &quot;Alice&quot;}
// Version 1.1 (backward compatible)
{&quot;id&quot;: 1, &quot;name&quot;: &quot;Alice&quot;, &quot;email&quot;: &quot;[email protected]&quot;}
// Version 1.2 (still backward compatible)
{&quot;id&quot;: 1, &quot;name&quot;: &quot;Alice&quot;, &quot;email&quot;: &quot;[email protected]&quot;, &quot;phone&quot;: &quot;555-1234&quot;}</code></pre>
<p><strong>Clients ignore unknown fields</strong> → No breaking changes.</p>
<hr>
<h3>Technique 2: Default Values</h3>
<p><strong>Strategy</strong>: Provide defaults for new required fields.</p>
<pre><code class="lang-python">from pydantic import BaseModel, Field
class User(BaseModel):
id: int
name: str
email: str = Field(default=&quot;[email protected]&quot;) # Default for old clients</code></pre>
<p><strong>Old requests</strong> (no email) → Use default <strong>New requests</strong> (with email) → Use provided value</p>
<hr>
<h3>Technique 3: Field Aliases</h3>
<p><strong>Strategy</strong>: Support both old and new field names.</p>
<pre><code class="lang-python">from pydantic import BaseModel, Field
class User(BaseModel):
user_id: int = Field(alias=&quot;id&quot;) # Accept both &quot;id&quot; and &quot;user_id&quot;
name: str</code></pre>
<p><strong>Accepts</strong>:</p>
<pre><code class="lang-json">{&quot;id&quot;: 1, &quot;name&quot;: &quot;Alice&quot;} // Old clients
{&quot;user_id&quot;: 1, &quot;name&quot;: &quot;Alice&quot;} // New clients</code></pre>
<hr>
<h2>Versioning Strategy Comparison</h2>
<p>| Strategy | Discoverability | Caching | Simplicity | Best For | |----------|----------------|---------|------------|----------| | <strong>URL Path</strong> | ⭐⭐⭐ High | ⭐⭐⭐ Easy | ⭐⭐⭐ Simple | Public APIs, REST | | <strong>Header (Accept)</strong> | ⭐ Low | ⭐ Complex | ⭐⭐ Moderate | Strict REST, Internal | | <strong>Query Param</strong> | ⭐⭐ Medium | ⭐⭐ Moderate | ⭐⭐⭐ Simple | Prototypes, Internal | | <strong>Custom Header</strong> | ⭐ Low | ⭐⭐ Moderate | ⭐⭐ Moderate | Microservices, Internal |</p>
<p><strong>Recommendation</strong>: Use <strong>URL Path Versioning</strong> for simplicity and discoverability unless strict REST compliance required.</p>
<hr>
<h2>Related Skills</h2>
<ul><li><code>fastapi-routing.md</code> - Organizing API routes and versioning</li><li><code>api-design-patterns.md</code> - RESTful API design principles</li><li><code>api-documentation.md</code> - Documenting versioned APIs (OpenAPI/Swagger)</li><li><code>database-migrations.md</code> - Versioning database schemas alongside APIs</li><li><code>feature-flags.md</code> - Using feature flags for gradual rollouts</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2025-10-18 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/api-api-versioning.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>