Skip to main content

Idempotency & Concurrency

Idempotency​

  • Required on every POST, PUT, PATCH with a body.
  • Header: Idempotency-Key: <ULID>.
  • Stored for 24h. Replay with same body ? cached response. Replay with different body ? 409 idempotency.replay_mismatch.

Optimistic concurrency​

  • Reads return ETag: "<version>".
  • Writes that mutate state must carry If-Match: "<version>".
    • Missing ? 428 concurrency.precondition_required.
    • Mismatch ? 412 concurrency.version_conflict.

End-to-end​

curl -X GET https://api.ghasi.io/api/v1/courses?cursor=eyJ2IjoxfQ \
  -H 'Authorization: Bearer <jwt>' \
  -H 'X-Tenant-Id: ten_01J…' \
  -H 'Accept-Language: en'