dev/atlas
한국어
/> API design

API Contract

API 계약

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

···
html
<div class="viz"><h3>CLIENT ↔ CONTRACT ↔ SERVER</h3><div class="row"><div class="box">v1<br>client</div><span class="arrow">→</span><div class="box code" id="schema">{ id }</div><span class="arrow">→</span><div class="box" id="verdict">PASS</div></div><div class="muted" id="note">required field preserved</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}#verdict{min-width:18%;border-color:var(--accent)}#verdict.fail{border-color:var(--accent-3);color:var(--accent-3)}#schema{white-space:nowrap;min-width:28%}
js
let broken=false;function draw(){broken=!broken;document.getElementById('schema').textContent=broken?'{ key }':'{ id, note? }';const verdict=document.getElementById('verdict');verdict.textContent=broken?'BREAK':'PASS';verdict.classList.toggle('fail',broken);document.getElementById('note').textContent=broken?'required id renamed':'optional note added'}draw();setInterval(draw,1600)
···

Schema Validation스키마 검증

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

···

API Backward CompatibilityAPI 하위 호환성

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

···

API VersioningAPI 버저닝

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

···

Contract testing계약 테스트

Check whether a provider’s response satisfies what its consumer expects.

An API contract states how to call an endpoint and what comes back. It covers paths and methods as well as field types, required properties, status codes, and authentication. A documented schema lets client and server implementations check against the same promise.

The demo shows an old client accepting an added optional field, then failing when a required field is renamed. Check consumers and compatibility before changing the contract.

When to use

Use it when teams or services implement against a shared API, especially a long lived public one.

Open as page ↗