İçeriğe geç
Muhammet Şafak
en
Web Geliştirme 3 dk okuma

API'de idempotency: aynı isteği güvenle tekrar etmek

Tekrarlanan API isteklerinin yan etki üretmemesini tasarlamak; idempotency anahtarları ve uygulama katmanında pratik çözümler.

Kısaca

Idempotent bir API işlemi, istek bir kez de gelse birçok kez de gelse aynı etkiyi bırakır. İstemcinin ürettiği idempotency key, sunucunun tekrar denemeleri tanımasını ve kayıtlı yanıtı dönmesini sağlar; böylece POST yeniden denemeleri güvenli olur.

Sunucu kasasında IDEMPOTENCY yazan mor ışıklı yuvaya sokulmuş metal kart; üzerinde KEY: X5F-912-Q8J kazıması

Şöyle bir senaryo düşünün: kullanıcı bir ödeme başlatıyor, istek yolda kayboluyor ya da istemci bir timeout alıyor. İstemci ne yapacak? Yeniden denemeli mi? Ödeme gerçekleşti mi gerçekleşmedi mi bilmiyor.

Bu belirsizlik, ağ üzerinden çalışan sistemlerin kaçınılmaz bir özelliğidir. İstek gönderildi ama yanıt alınamadı — bu, “işlem yapılmadı” anlamına gelmiyor. Belki işlem tamamlandı, yanıt dönmedi. Belki işlem yarıda kaldı. Belki hiç başlamadı.

Çözüm bu belirsizliği kabul edip, tekrarlanan isteğin güvenli olmasını tasarlamak. Bu kavrama idempotency (eşgüçlülük) deniyor.

Idempotency nedir?

Matematikte bir operasyon idempotent ise, aynı girdi ile kaç kez uygulanırsa uygulansın sonuç değişmez. API bağlamında: aynı isteği birden fazla göndermek, bir kez göndermekle aynı etkiyi yaratmalıdır.

Tanım HTTP’nin kendi spesifikasyonunda duruyor. RFC 9110’un ifadesiyle bir yöntem, “aynı isteğin birden çok kez gönderilmesinin sunucu üzerinde amaçlanan etkisi tek bir isteğinkiyle aynıysa” idempotenttir; spesifikasyonun tanımladığı yöntemler arasında PUT, DELETE ve güvenli (safe) yöntemler idempotenttir. HTTP yöntemleri bu açıdan farklı davranır:

  • GET, HEAD, OPTIONS, PUT, DELETE — doğası gereği idempotent. Aynı GET /users/5 isteğini on kez gönderin; sonuç aynı.
  • POST — doğası gereği idempotent değil. Her POST /payments yeni bir ödeme oluşturabilir.

Ayrım pratikte şu yüzden önemli: RFC, idempotent bir yöntemin “istemci yanıtı okuyamadan bağlantı koptuğunda otomatik olarak tekrarlanabileceğini” söylüyor, ama idempotent olmayan bir yöntem için istemcinin bunu kendiliğinden yapmaması gerektiğini ekliyor. Yani POST’ta yeniden denemeyi güvenli kılmak bizim işimiz.

Sorun genellikle POST ile ve durumu değiştiren işlemlerde ortaya çıkıyor.

Idempotency anahtarı

Çözümün özü şu: istemci, her benzersiz operasyon için bir key üretir ve bunu istekle birlikte gönderir. Sunucu bu anahtarı gördüğünde şunu yapar: “Bu anahtarla daha önce bir istek işledim mi? Evet ise, aynı yanıtı dönerim; hayır ise, işlemi yaparım ve sonucu bu anahtarla saklarım.”

İstemci aynı anahtarla yeniden denerse, işlem tekrar çalışmaz; daha önce üretilen yanıt döner.

POST /api/payments
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "amount": 9900,
  "currency": "TRY",
  "method": "card"
}

Bu kalıbın en bilinen uygulaması Stripe. Kendi dokümanına göre anahtarı istemci üretiyor, Stripe anahtar için V4 UUID öneriyor ve anahtarlar en az 24 saat yaşlandıktan sonra sistemden silinebiliyor. Aynı yaklaşımı kendi API’lerinizde de uygulayabilirsiniz.

Laravel’de uygulama

Temel akış şu: istek geldiğinde önce önbellekte (veya veritabanında) bu anahtara karşılık bir kayıt var mı kontrol et; varsa saklı yanıtı dön; yoksa işlemi çalıştır, yanıtı sakla ve dön.

// app/Http/Middleware/IdempotencyMiddleware.php
class IdempotencyMiddleware
{
    public function handle(Request $request, Closure $next): Response
    {
        $key = $request->header('Idempotency-Key');

        if (!$key) {
            return $next($request);
        }

        $cacheKey = 'idempotency:' . auth()->id() . ':' . $key;

        if ($cached = Cache::get($cacheKey)) {
            return response()->json(
                json_decode($cached['body'], true),
                $cached['status']
            );
        }

        $response = $next($request);

        // 5xx dışındaki yanıtları sakla — 4xx dahil
        if ($response->getStatusCode() < 500) {
            Cache::put($cacheKey, [
                'body'   => $response->getContent(),
                'status' => $response->getStatusCode(),
            ], now()->addHours(24));
        }

        return $response;
    }
}

Birkaç not:

Kullanıcı bazlı anahtar. auth()->id() ile anahtarı kullanıcıya bağlıyorum. Farklı kullanıcıların aynı anahtarı göndermesi durumunda çakışma olmasın.

Hata yanıtlarını saklamak. Yukarıdaki kodda 5xx saklanmıyor; istemci yeniden deneyebilmeli. 4xx (istemci hatası) ise saklanıyor: aynı hatalı isteği yeniden gönderirseniz aynı hata döner.

Bu bilinçli bir tercih ve Stripe’ınkinden farklı: Stripe ilk isteğin durum kodunu ve gövdesini, istek başarılı olsun ya da olmasın saklıyor — aynı anahtarla gelen sonraki istekler 500 hatalarını bile aynen geri alıyor. Seçim, “yeniden deneme sunucu hatasını aşabilmeli mi” sorusuna verdiğiniz cevaba bağlı. Sunucuda geçici bir arıza bekliyorsanız benim yaptığım gibi 5xx’i saklamayın; yeniden denemenin kesinlikle yeni bir yan etki üretmemesini istiyorsanız Stripe’ın davranışı daha güvenli.

Saklama süresi. 24 saat makul bir başlangıç — Stripe da anahtarları en az bir gün yaşlandıktan sonra siliyor. İş gereksinimlerine göre ayarlanabilir.

Anahtarı kim üretir?

İstemci üretmeli. Sunucu üretirse anlam kalmaz: sunucu zaten işlemi yaptı, yanıtı döndü; anahtar sonradan üretilmiş oldu. Stripe da bunu böyle tarif ediyor: anahtarı istemci üretir, sunucu onu aynı isteğin sonraki denemelerini tanımak için kullanır. İstemcinin elinde bir UUID v4 ya da benzeri benzersiz bir tanımlayıcı olmalı ve bu tanımlayıcıyı yeniden deneme boyunca korumalı.

React Native tarafında:

import { randomUUID } from "expo-crypto";

async function createPayment(amount: number) {
  const idempotencyKey = randomUUID();

  try {
    const response = await api.post(
      "/payments",
      { amount },
      { headers: { "Idempotency-Key": idempotencyKey } }
    );
    return response.data;
  } catch (error) {
    if (isNetworkError(error)) {
      // Aynı anahtarla yeniden dene
      return retryWithSameKey(idempotencyKey, amount);
    }
    throw error;
  }
}

Anahtar, ödeme nesnesi oluşturulduğunda üretilir; yeniden denemede aynı anahtar kullanılır. Sunucu ikinci isteği görünce zaten işlemi yapmış olduğunu anlayacak.

Sadece ödeme değil

Idempotency’nin değeri ödeme sistemleriyle sınırlı değil. Kullanıcı kaydı, e-posta gönderimi, stok rezervasyonu — kullanıcı için görünür bir yan etkisi olan her POST işlemi bu desenden yararlanabilir.

Özellikle mobil uygulamalarda ağ bağlantısı güvenilmez; kullanıcı “Gönder” butonuna birden fazla kez basabilir. Bu durumları ele almak için istemci tarafında çift gönderimi engellemek (buton devre dışı bırakmak) yeterli değil; sunucunun da hazır olması gerekir.

Bu yazı API tarafında kalıyor. Tüketici tarafı için — broker’ın çökmeden sonra aynı mesajı iki kez teslim etmesi ve unique constraint’li bir dedup deposunun bunu nasıl yuttuğu — Idempotency: Aynı Mesaj İki Kez Geldiğinde yazısına bakın.

Tasarımı bu varsayım üzerine kurmak — “istek tekrar gelebilir” — daha dayanıklı bir API ortaya çıkarır.


Kaynaklar

Sık sorulanlar

6 soru

  • API'lerde idempotency nedir?

    Aynı isteği birden fazla kez göndermenin, bir kez göndermekle tam olarak aynı etkiyi yaratmasıdır. RFC 9110, bir HTTP yöntemini, aynı isteğin birden çok kez yapılmasının sunucudaki amaçlanan etkisi tek istekle aynıysa idempotent sayar. GET, HEAD, OPTIONS, PUT ve DELETE doğası gereği idempotenttir; POST değildir.

  • Bir istek zaman aşımına uğradığında idempotency neden önemli?

    Çünkü istemci işlemin tamamlandığını, yarıda kesildiğini ya da hiç başlamadığını bilemez. Bağlantı koparsa idempotent bir istek otomatik tekrarlanabilir, ama istemci POST gibi idempotent olmayan bir yöntemi otomatik olarak yeniden denememelidir. Yani POST'ta tekrarları güvenli kılmak bizim işimiz.

  • Idempotency anahtarı nasıl çalışır?

    İstemci her işlem için benzersiz bir anahtar üretir ve isteğiyle birlikte gönderir, örneğin bir Idempotency-Key header'ında. Sunucu bu anahtarı daha önce işlemişse saklanan yanıtı döner; işlememişse işlemi yapar ve sonucu anahtarın altında saklar. Böylece tekrar eden istek işlemi bir daha çalıştırmaz.

  • Idempotency anahtarını kim üretir?

    İstemci. Sunucunun ürettiği anahtar anlamsız olurdu; çünkü anahtar var olduğunda sunucu işlemi zaten yapmış ve yanıtı dönmüştür. İstemci bir UUID v4 ya da benzeri benzersiz bir tanımlayıcı kullanır ve aynı tanımlayıcıyı tekrar denemeler boyunca korur.

  • Hata yanıtları bir anahtar için saklanmalı mı?

    Bu bilinçli bir tercih. Benim Laravel middleware'imde 5xx yanıtları saklanmaz, böylece tekrar deneme sunucu tarafı bir hatayı aşabilir; 4xx yanıtları saklanır. Stripe ise sonucu ne olursa olsun ilk isteğin durum kodunu ve gövdesini kaydeder; tekrar denemenin yeni bir yan etki üretmesi kesinlikle istenmiyorsa daha güvenli davranış budur.

  • Anahtarlar ne kadar süre saklanmalı?

    24 saat makul bir başlangıç noktasıdır; Stripe de anahtarları en az 24 saatlik olduklarında silebilir. İş gereksinimlerinize göre ayarlayın. Ayrıca anahtarı kimliği doğrulanmış kullanıcıya bağlıyorum; böylece farklı kullanıcılar tesadüfen aynı anahtarı gönderse de çakışma olmuyor.

Bu konudaki deneyler

Kaydırmalı bilgi yarışmasında skoru istemci hesaplıyor, sunucu server_nonce ve HMAC imzasıyla doğruluyor. Bu güven sorununun yapım notları.

Şu an ne yapıyor

Kaydırmalı doğru/yanlış bilgi yarışması bir mobil uygulama olarak çekirdek döngüsüyle uçtan uca çalışıyor; skoru istemci üretse de server_nonce ve HMAC imzasıyla sunucu tarafında doğrulanıyor. swipenor.com uygulamanın tanıtım sayfasıdır, oyunun kendisi değil.

Mobil Laravel PHP PostgreSQL +6 daha
Temmuz 2026 — Eylül 2026

Yorumlar

Yorum yapmak için GitHub hesabınızla giriş yapmanız yeterli. Yorumlar GitHub Discussions üzerinde saklanır.

İlgili Yazılar

Sitede Ara

Yazı, proje ve sayfalarda arama yapmak için yazmaya başlayın.

Esc ile kapat Pagefind ile güçlendirildi