dev/atlas
한국어
/> API design

API Backward Compatibility

API 하위 호환성

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

···
html
<div class="viz"><h3>OLD CLIENT EXPECTS id</h3><div class="row"><div class="box code" id="response">{ id, name, note? }</div><span class="arrow">→</span><div class="box" id="result">COMPATIBLE</div></div><div class="muted" id="change">optional field added</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}#response{min-width:54%}#result{min-width:27%;color:var(--accent);border-color:var(--accent)}#result.break{color:var(--accent-3);border-color:var(--accent-3)}
js
let broken=false;function draw(){broken=!broken;document.getElementById('response').textContent=broken?'{ name }':'{ id, name, note? }';const r=document.getElementById('result');r.textContent=broken?'BREAKING':'COMPATIBLE';r.classList.toggle('break',broken);document.getElementById('change').textContent=broken?'required id removed':'optional field added'}draw();setInterval(draw,1600)
···

API ContractAPI 계약

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

···

Schema Validation스키마 검증

Validate input types, required fields, and ranges against a schema at the API boundary.

···

API VersioningAPI 버저닝

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

···

OpenAPI Nested TagsOpenAPI 중첩 태그

OpenAPI 3.2 parent and kind organize operation tags into a documentation hierarchy.

Backward compatibility means an existing consumer still works after a new API version is deployed. Adding an optional response field is often tolerated, while removing or changing a required field may break old code. The actual result depends on consumer parsers and validation rules.

The demo passes an optional addition and fails when required id disappears. Use consumer contract tests and usage data to judge impact, and plan migration for breaking changes.

When to use

Check it before changing request or response schemas of a live API.

Open as page ↗