dev/atlas
한국어
/> API design

Idempotency Key

멱등성 키

A repeated request key prevents a retried creation from running the operation twice.

···
html
<div class="viz"><h3>POST /orders · KEY K7</h3><div class="row"><div class="box">try 1<br>try 2</div><span class="arrow">→</span><div class="box" id="gate">key store</div><span class="arrow">→</span><div class="box">orders <b id="count" class="accent">0</b></div></div><div class="muted" id="result">processing…</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}#gate{transition:background .3s,border-color .3s}#gate.hit{border-color:var(--accent);background:color-mix(in srgb,var(--accent) 15%,var(--surface))}
js
let retry=false;function draw(){retry=!retry;document.getElementById('count').textContent='1';document.getElementById('gate').classList.toggle('hit',retry);document.getElementById('result').textContent=retry?'attempt 2 · cached result · no new order':'attempt 1 · order created'}draw();setInterval(draw,1600)
···

REST Resource ModelREST 자원 모델

URIs identify resources while HTTP methods express reading, creating, and changing them.

···

Webhook Delivery웹훅 전달

A provider sends an event to a receiver URL and retries when delivery fails.

···

API Error EnvelopeAPI 오류 응답 형식

A consistent code, message, and details shape simplifies client handling across failures.

···

API ContractAPI 계약

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

An idempotency key identifies one client operation. The server stores the key and outcome for a defined period, returning that outcome for a retry with the same key. This helps when the network drops a response after the operation succeeded.

In the demo, two POST attempts share a key and create one order. The server must define key scope, retention time, and how it handles a different payload under the same key.

When to use

Use it for payment or order creation where retries could duplicate a side effect.

Open as page ↗