Idempotency

Iara Data uses idempotency keys to prevent duplicate operations. This is critical for data integrity — if a request is sent twice (e.g., due to a network retry), only the first one is executed.

How It Works

Include an Idempotency-Key header on all mutating requests (POST, PUT, PATCH, DELETE):

curl -X POST https://lake.iaradata.com/api/v1/ingest/metrics \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Idempotency-Key: unique-uuid-12345" \
  -H "Content-Type: application/json" \
  -d '{"table": "sales", "rows": [...]}'

Behavior

Scenario	What Happens
First request with key abc123	Request is executed normally, result is cached
Second request with same key abc123	Returns the cached result without re-executing
Different key xyz789	New request is executed normally

Idempotency Explorer

Admins can browse cached idempotent responses at Settings → Idempotency Explorer.

Filters

Filter	Description
Key	Search by idempotency key
Method	GET, POST, PUT, PATCH, DELETE
Path	URL path prefix
Status Code	HTTP response status
Since	Show only entries after a date

Detail View

Click on any entry to see:

• Key — The idempotency key
• Method & Path — The request endpoint
• Body Hash — Hash of the request body
• Status — Response status code
• Full Response — The cached response body
• Timestamp — When it was cached

Replay

Admins can click Replay to re-execute a cached request. This is useful for debugging or retrying after a fix.

info

Best practice: Use UUIDs or deterministic keys for idempotency. For example, ingest-{fileHash}-{timestamp} ensures the same file isn't ingested twice.