Idempotency

Yazma işlemleri (rezervasyon oluşturma, webhook aboneliği vb.) ağ hatalarına karşı idempotency anahtarı ile korunmalıdır. Bu sayede aynı istek birden çok kez tekrarlanırsa bile işlem yalnızca bir kez uygulanır.

Nasıl Çalışır?

POST isteklerine Idempotency-Key başlığını ekleyin:

curl -X POST https://example.com/apiv2/partner-api/v1/reservations/hotel \
  -H "Authorization: Bearer ..." \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

• Aynı anahtar ve aynı gövde ile tekrar gönderildiğinde: ilk yanıt aynen geri döner, işlem tekrarlanmaz.
• Aynı anahtar ile farklı bir gövde gönderildiğinde: 409 IDEMPOTENCY_KEY_REUSED hatası döner.
• Anahtar 24 saat boyunca saklanır.

Önerilen Uygulama

• Her POST isteği için yeni bir UUID v4 üretin.
• Başarılı yanıtın ardından anahtarı istemci tarafında saklamanıza gerek yoktur.
• Zaman aşımı veya ağ hatası durumunda aynı anahtar ile yeniden deneyin.

Node.js örneği

import crypto from 'crypto';

const idempotencyKey = crypto.randomUUID();

async function createReservationWithRetry(body, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fetch(`${baseUrl}/reservations/hotel`, {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${token}`,
          'Idempotency-Key': idempotencyKey,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(body),
      });
    } catch (err) {
      if (i === maxRetries - 1) throw err;
      await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
    }
  }
}