Get started
API conventions

Idempotency

Idempotency

Every write on the Map Studio API takes an Idempotency-Key header. Pick one value per write, a UUID, and send it again unchanged on every retry. The first request runs; a repeat gets the first answer back, and nothing runs twice.

The samples below create a collection, retry it with the same key, and delete it. They need a session token minted for a member, as act as a member shows.

IDEMPOTENCY_KEY=$(uuidgen)

# Send the write twice with one key, as a retry after a lost answer would.
for attempt in 1 2; do
  RESPONSE=$(curl -s -i -X POST https://api.mountaya.com/v1/collections \
    -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY" \
    -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
    -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
    -H "Content-Type: application/json" \
    -d '{"name": "Docs retries", "is_private": true}')
  echo "$RESPONSE" | grep -iE '^(HTTP|location|idempotent-replayed)'
done

# A delete takes a key of its own.
curl -s -X DELETE "https://api.mountaya.com/v1/collections/$(echo "$RESPONSE" | tail -n 1 | jq -r .data.id)" \
  -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY" \
  -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
Response
HTTP/1.1 201 Created
Location: /v1/collections/e63bf5f0-40d7-445a-9a87-6cc839c66385
HTTP/1.1 201 Created
Idempotent-Replayed: true
Location: /v1/collections/e63bf5f0-40d7-445a-9a87-6cc839c66385

The second answer is the first one, replayed: the same status, body, and Location, marked Idempotent-Replayed: true.

What a repeat gets

You send the key againThe answer
With a different request400 Bad Request at the Idempotency-Key header. A key names one write.
With the same request, after the first finishedThe first answer, replayed, with Idempotent-Replayed: true.
With the same request, while the first still runs409 coded IDEMPOTENCY_KEY_IN_USE, with Retry-After: 1. Wait, then resend.
After a write whose answer was lost409 coded IDEMPOTENCY_ANSWER_UNAVAILABLE. The write was made: read the resource instead.

A key is kept for 12 hours. Never reuse one for a different write.

Next steps

Last updated