API 버저닝

API Versioning

기존 소비자를 유지하면서 바뀐 계약을 새 버전으로 제공하는 전환 전략입니다.

···
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 버저닝은 클라이언트가 기대하는 계약을 식별하고 여러 계약을 일정 기간 함께 제공하는 방법입니다. 경로, 헤더, 미디어 타입 등으로 버전을 고를 수 있습니다. 새 버전은 파괴적인 변경을 분리하지만 운영 중인 버전 수가 늘면 테스트·문서·지원 비용도 커집니다.

데모는 v1 요청과 v2 요청을 각각의 응답 계약으로 라우팅하고, 비교 막대를 움직여 두 계약의 필드 차이를 보여줍니다. 버전 번호만 올리기보다 실제 호환성 검사와 구버전 종료 시점을 함께 계획해야 합니다.

언제 쓰나

운영 중인 API에 기존 소비자를 깨는 변경이 필요할 때 사용합니다.

페이지로 열기 ↗