dev/atlas
한국어
/> API design

API Versioning

API 버저닝

Offer a changed contract as a new version while existing consumers keep working.

···
html
<div class="viz"><h3>VERSION ROUTING</h3><div class="versions"><div class="box"><b>v1</b><br>{ id, name }</div><div class="divider" id="divider"></div><div class="box"><b>v2</b><br>{ key, title }</div></div><div class="muted" id="version-note">v1 client → v1 contract</div></div>
css
.viz{width:94%;height:88%;max-width:960px;padding:clamp(10px,2vmin,18px);border:1px solid var(--line);border-radius:14px;background:var(--surface);font:600 clamp(12px,1.35vw,16px)/1.35 var(--font-sans,system-ui,sans-serif);display:flex;flex-direction:column;gap:clamp(7px,1.8vmin,13px);overflow:hidden}.viz h3{margin:0;color:var(--accent);font:700 clamp(12px,1.35vw,16px)/1.2 var(--font-sans,system-ui,sans-serif);letter-spacing:.04em}.viz .row{display:flex;align-items:center;justify-content:center;gap:clamp(5px,1.4vmin,12px);flex:1;min-height:0}.viz .box{padding:clamp(5px,1.5vmin,12px);border:1px solid var(--line);border-radius:9px;background:var(--bg);text-align:center}.viz .muted{color:var(--muted)}.viz .accent{color:var(--accent)}.viz .code{font-family:ui-monospace,monospace}.viz .pill{padding:3px 7px;border:1px solid var(--line);border-radius:99px;white-space:nowrap}.viz .active{border-color:var(--accent);background:color-mix(in srgb,var(--accent) 12%,var(--surface))}.viz .arrow{color:var(--accent);font:700 18px ui-monospace,monospace}.versions{display:flex;align-items:center;justify-content:center;gap:8px;flex:1}.versions .box{width:38%;font:600 clamp(12px,1.35vw,16px)/1.5 var(--font-sans)}.versions b{color:var(--accent)}.versions .chosen{border-color:var(--accent);background:color-mix(in srgb,var(--accent) 14%,var(--surface))}.divider{width:4px;height:75%;background:var(--accent);border-radius:9px;transition:transform .5s}
js
let v=0;function draw(){v=1-v;document.querySelectorAll('.versions .box').forEach((el,i)=>el.classList.toggle('chosen',i===v));document.getElementById('divider').style.transform='translateX('+(v?12:-12)+'px)';document.getElementById('version-note').textContent='v'+(v+1)+' client → v'+(v+1)+' contract'}draw();setInterval(draw,1350)
···

API Backward CompatibilityAPI 하위 호환성

Check whether a new server contract still satisfies existing client expectations.

···

API ContractAPI 계약

Paths, requests, responses, and failures form a shared promise between client and server.

···

Content Negotiation콘텐츠 협상

The Accept header asks for a representation and the server selects a supported response type.

···

Token bucket rate limiting토큰 버킷 속도 제한

Requests spend replenishing tokens, controlling average API rate while permitting short bursts.

API versioning identifies the contract a client expects and serves multiple contracts during a transition. A path, header, or media type can select the version. A new version isolates breaking changes, but each live version adds testing, documentation, and support cost.

The demo routes v1 and v2 requests to their respective response contracts and moves a divider to show the field difference. Pair version numbers with compatibility checks and a retirement plan for old clients.

When to use

Use it when a live API needs a change that would break existing consumers.

Open as page ↗