mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
Every page now loads /webmcp.js, scripts/webmcp.ts with its types stripped (npm run webmcp). Where the browser has document.modelContext it registers two read-only tools: search_skills over the published skills index, and get_skill, which returns a skill's markdown checked against the index digest. The markdown alternate link moves from build.py to site.py, so CI holds every page to it. The API catalog gains the site itself (llms.txt and the skills index) and hanzo.ai/agents; the live discovery check now fetches every catalog link. tests/site.mjs drives the tools through a recording modelContext, and checks a browser without one loads clean.
606 lines
30 KiB
HTML
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="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/api-api-versioning">
|
|
<link rel="alternate" type="text/markdown" href="/api-api-versioning.md">
|
|
<script type="module" src="/webmcp.js"></script>
|
|
</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("/v1/users/{user_id}")
|
|
async def get_user_v1(user_id: int):
|
|
return {"id": user_id, "name": "Alice"}
|
|
|
|
# Version 2 (with email field)
|
|
@app.get("/v2/users/{user_id}")
|
|
async def get_user_v2(user_id: int):
|
|
return {
|
|
"id": user_id,
|
|
"name": "Alice",
|
|
"email": "[email protected]"
|
|
}</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("/users/{user_id}")
|
|
async def get_user(
|
|
user_id: int,
|
|
accept: str = Header(default="application/vnd.api.v1+json")
|
|
):
|
|
if "v2" in accept:
|
|
return {
|
|
"id": user_id,
|
|
"name": "Alice",
|
|
"email": "[email protected]"
|
|
}
|
|
elif "v1" in accept:
|
|
return {"id": user_id, "name": "Alice"}
|
|
else:
|
|
raise HTTPException(400, "Unsupported API version")</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("/users/{user_id}")
|
|
async def get_user(
|
|
user_id: int,
|
|
api_version: int = Query(default=1)
|
|
):
|
|
if api_version == 2:
|
|
return {
|
|
"id": user_id,
|
|
"name": "Alice",
|
|
"email": "[email protected]"
|
|
}
|
|
else:
|
|
return {"id": user_id, "name": "Alice"}</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("/users/{user_id}")
|
|
async def get_user(
|
|
user_id: int,
|
|
x_api_version: int = Header(default=1)
|
|
):
|
|
if x_api_version == 2:
|
|
return {
|
|
"id": user_id,
|
|
"name": "Alice",
|
|
"email": "[email protected]"
|
|
}
|
|
else:
|
|
return {"id": user_id, "name": "Alice"}</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
|
|
{"name": "Alice"}
|
|
|
|
// After (optional email)
|
|
{"name": "Alice", "email": "[email protected]"}</code></pre>
|
|
<p>✅ <strong>Adding new fields to response</strong>:</p>
|
|
<pre><code class="lang-json">// Before
|
|
{"id": 1, "name": "Alice"}
|
|
|
|
// After (added email)
|
|
{"id": 1, "name": "Alice", "email": "[email protected]"}</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
|
|
{"id": 1, "name": "Alice", "email": "[email protected]"}
|
|
|
|
// After (removed email) - BREAKS CLIENTS
|
|
{"id": 1, "name": "Alice"}</code></pre>
|
|
<p>❌ <strong>Renaming fields</strong>:</p>
|
|
<pre><code class="lang-json">// Before
|
|
{"user_id": 1}
|
|
|
|
// After - BREAKS CLIENTS
|
|
{"id": 1}</code></pre>
|
|
<p>❌ <strong>Changing field types</strong>:</p>
|
|
<pre><code class="lang-json">// Before
|
|
{"created_at": "2025-01-15"}
|
|
|
|
// After - BREAKS CLIENTS
|
|
{"created_at": 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("/v1/users/{user_id}")
|
|
async def get_user_v1(user_id: int, response: Response):
|
|
# Add deprecation warning
|
|
response.headers["Deprecation"] = "true"
|
|
response.headers["Sunset"] = "2025-07-01"
|
|
response.headers["Link"] = '</v2/users>; rel="successor-version"'
|
|
|
|
return {"id": user_id, "name": "Alice"}</code></pre>
|
|
<p><strong>Communication</strong>:</p>
|
|
<pre><code>Subject: API v1 Deprecation Notice
|
|
|
|
We'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("/v1/users/{user_id}")
|
|
async def get_user_v1(user_id: int, response: Response):
|
|
response.headers["X-Deprecation-Warning"] = "v1 will sunset on 2025-07-01"
|
|
|
|
return {
|
|
"id": user_id,
|
|
"name": "Alice",
|
|
"_deprecation": {
|
|
"message": "This endpoint will be removed on 2025-07-01",
|
|
"migration_guide": "https://docs.api.com/v1-to-v2"
|
|
}
|
|
}</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("/v1/users/{user_id}")
|
|
async def get_user_v1(user_id: int):
|
|
raise HTTPException(
|
|
status_code=410,
|
|
detail={
|
|
"error": "This API version has been sunset",
|
|
"sunset_date": "2025-07-01",
|
|
"migration_guide": "https://docs.api.com/v1-to-v2",
|
|
"new_endpoint": "/v2/users/{user_id}"
|
|
}
|
|
)</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("/v1/users/{user_id}")
|
|
async def get_user_v1(user_id: int):
|
|
return {"id": user_id, "name": "Alice"}
|
|
|
|
# v2/users.py
|
|
@router.get("/v2/users/{user_id}")
|
|
async def get_user_v2(user_id: int):
|
|
return {
|
|
"id": user_id,
|
|
"name": "Alice",
|
|
"email": "[email protected]"
|
|
}</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 {
|
|
"id": user_id,
|
|
"name": "Alice",
|
|
"email": "[email protected]"
|
|
}
|
|
|
|
# api/v1.py
|
|
@app.get("/v1/users/{user_id}")
|
|
async def get_user_v1(user_id: int):
|
|
data = get_user_data(user_id)
|
|
# Adapter: remove email for v1
|
|
return {"id": data["id"], "name": data["name"]}
|
|
|
|
# api/v2.py
|
|
@app.get("/v2/users/{user_id}")
|
|
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 ["id", "name"]}
|
|
else:
|
|
return data
|
|
|
|
return wrapper
|
|
|
|
@version_aware
|
|
async def get_user(user_id: int):
|
|
return {
|
|
"id": user_id,
|
|
"name": "Alice",
|
|
"email": "[email protected]"
|
|
}</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
|
|
{"id": 1, "name": "Alice"}
|
|
|
|
// Version 1.1 (backward compatible)
|
|
{"id": 1, "name": "Alice", "email": "[email protected]"}
|
|
|
|
// Version 1.2 (still backward compatible)
|
|
{"id": 1, "name": "Alice", "email": "[email protected]", "phone": "555-1234"}</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="[email protected]") # 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="id") # Accept both "id" and "user_id"
|
|
name: str</code></pre>
|
|
<p><strong>Accepts</strong>:</p>
|
|
<pre><code class="lang-json">{"id": 1, "name": "Alice"} // Old clients
|
|
{"user_id": 1, "name": "Alice"} // 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> |