API 계약

API Contract

경로·요청·응답·오류 규칙을 클라이언트와 서버가 함께 지키는 약속으로 정의합니다.

···
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)

API 계약은 호출 방법과 결과의 형태를 명시합니다. 경로와 메서드뿐 아니라 필드 타입, 필수 여부, 상태 코드, 인증 조건까지 포함합니다. 이를 문서와 스키마로 표현하면 클라이언트·서버가 각자 구현해도 같은 기준으로 검증할 수 있습니다.

데모에서는 응답에 선택 필드를 추가할 때 구형 클라이언트가 계속 통과하지만, 필수 필드 이름을 바꾸면 계약 연결이 끊깁니다. 변경 전에는 소비자와 호환성 영향을 먼저 확인해야 합니다.

언제 쓰나

여러 팀·서비스가 API를 독립 구현하거나 공개 API를 오래 유지할 때 중요합니다.

페이지로 열기 ↗