WordPress REST API Batch İstekleri ve Performans Optimizasyonu Rehberi

Gelişmiş web uygulamalarında ve headless WordPress mimarilerinde istemci ile sunucu arasındaki veri trafiğini yönetmek en büyük performans darboğazlarından biridir. Mobil bir uygulama veya JavaScript tabanlı bir ön yüz geliştirirken onlarca farklı veriyi (yazılar, kategoriler, kullanıcı bilgileri, özel alanlar) çekmek için ardışık HTTP istekleri atmak ağ gecikmesini (latency) katlayarak artırır. İşte bu noktada WordPress REST API Batch İstekleri devreye girer. Tek bir HTTP bağlantısı üzerinden birden fazla REST API talebini paketleyip sunucuya göndermenizi sağlayan bu mekanizma, veri iletim sürelerini radikal şekilde düşürür.

Modern web ekosisteminde istemci taraflı optimizasyon sadece görselleri sıkıştırmaktan ibaret değildir. API seviyesindeki gecikmeleri optimize etmek, özellikle mobil ağlarda kullanıcı deneyimini doğrudan etkiler. Bu rehberde, WordPress REST API Batch isteklerinin nasıl çalıştığını, mimari arka planını, kod örnekleriyle adım adım uygulanmasını ve sunucu tarafındaki performans optimizasyonlarını derinlemesine inceleyeceğiz. REST API'nin temel kavramlarına uzak kalmak istemiyorsanız API Nedir? REST API Temelleri ve Kullanımı başlıklı içeriğimize göz atabilirsiniz.

WordPress REST API Batch İstekleri Nasıl Çalışır?

WordPress REST API mimarisinde istemciler normal şartlarda her bir kaynak için ayrı bir endpoint'e HTTP isteği gönderir. Örneğin 5 farklı yazıyı güncellemek ve 3 yeni yorum çekmek için toplam 8 ayrı HTTP GET/POST/PUT isteği yapmanız gerekir. Her HTTP isteği; DNS sorgusu, TCP el sıkışması (handshake), TLS/SSL güvenlik doğrulaması ve HTTP başlıklarının (headers) taşınması anlamına gelir. Bu işlem, mobil bağlantılarda saniyeler süren gecikmelere yol açar.

Batch (toplu) istekler ise istemcinin tüm bu talepleri tek bir JSON gövdesi altında toplamasına ve /wp-json/wp/v2/batch endpoint'ine tek bir POST isteği olarak göndermesine olanak tanır. WordPress çekirdeği bu isteği aldığında dahili bir döngü başlatır ve ana HTTP sunucusu katmanından bağımsız olarak WP_REST_Server::dispatch() metodunu kullanarak istekleri uygulama seviyesinde sırayla işler.

İşlem sırası şu şekilde gerçekleşir:

Bu yaklaşım sayesinde 20 ayrı HTTP bağlantısı kurmak yerine tek bir HTTP bağlantısı kurulur. Sunucu tarafında PHP süreci tek bir başlatma (bootstrap) maliyeti ile birden fazla işlemi tamamlar. Özel endpoint yapıları hakkında daha detaylı teknik bilgi almak için WordPress REST API Kullanım Rehberi: Özel Endpoint Oluşturma yazımızı okuyabilirsiniz.

Batch İsteklerinin Avantajları ve Performans Metrikleri

Batch isteklerin getirdiği performans avantajı teorik bir kazanım değil, doğrudan ölçülebilir bir hız artışıdır. İletişim maliyetinin en büyük kısmı veri transferinden ziyade bağlantının kurulması (round-trip time - RTT) sırasındaki bekleme süreleridir.

Bir senaryo üzerinden performans farkını inceleyelim: Mobil bir kullanıcının ortalama 80ms ağ gecikmesine (RTT) sahip bir 4G ağında olduğunu varsayalım. Siteden 10 adet içerik ve bunlara ait meta verilerin çekilmesi gereksin.

• Geleneksel İstek Yaklaşımı: 10 ayrı HTTP isteği 80ms RTT = Sadece bağlantı kurma gecikmesi 800ms. Buna sunucunun her istekte WordPress'i yeniden yükleme (bootstrap) süresi (ortalama 150ms 10 = 1500ms) eklendiğinde toplam işlem süresi 2300ms seviyesine ulaşır.
• Batch İstek Yaklaşımı: 1 tek HTTP isteği * 80ms RTT = 80ms bağlantı gecikmesi. Sunucu tarafında tek bir WordPress bootstrap maliyeti (150ms) + 10 dahili dispatch süresi (ortalama 100ms toplam). Toplam yanıt süresi yaklaşık 330ms seviyesine geriler.

Bu senaryoda elde edilen yaklaşık %85'lik zaman tasarrufu, headless uygulamalarınızın ve dinamik panellerinizin ışık hızında çalışmasını sağlar. Ağ bant genişliği kullanımı azaldığı gibi sunucunun ağ arayüzündeki yük de ciddi oranda düşer.

Adım Adım Batch İstek Gönderme ve Kod Örnekleri

Batch isteklerinin gücünü kullanmak için istemci tarafında hazırlanan verinin WordPress'in beklediği standart biçimde sunulması gerekir. WordPress REST API batch endpoint'i /wp-json/wp/v2/batch adresidir ve gövdesinde requests adında bir dizi kabul eder.

1. JSON Payload Yapısının Hazırlanması

İstek paketinde her bir alt istek için method, path, headers ve opsiyonel olarak body parametreleri tanımlanır.

{
  "validation": "require-all-validate",
  "requests": [
    {
      "method": "POST",
      "path": "/wp/v2/posts",
      "body": {
        "title": "Batch ile Oluşturulan İlk Yazı",
        "status": "publish",
        "content": "Bu yazı toplu REST API isteği ile eklendi."
      }
    },
    {
      "method": "POST",
      "path": "/wp/v2/posts",
      "body": {
        "title": "Batch ile Oluşturulan İkinci Yazı",
        "status": "draft"
      }
    },
    {
      "method": "GET",
      "path": "/wp/v2/categories?per_page=5"
    }
  ]
}

Buradaki validation parametresi isteğe bağlıdır. require-all-validate değeri verildiğinde, alt isteklerden birinde doğrulama hatası çıkarsa tüm toplu işlem durdurulur.

2. JavaScript (Fetch API) İle Batch İstek Gönderme

Frontend veya Node.js ortamında REST API'ye toplu istek göndermek için modern JavaScript kullanabilirsiniz. Aşağıda WordPress Nonce yetkilendirmesi içeren örnek bir fetch uygulaması yer almaktadır:

async function sendWordPressBatch() {
  const restUrl = 'https://ornek-siteniz.com/wp-json/wp/v2/batch';
  const wpNonce = '1234567890'; // wp_localize_script ile aktarılan güvenli nonce

  const batchData = {
    validation: 'normal',
    requests: [
      {
        method: 'PUT',
        path: '/wp/v2/posts/42',
        body: { title: 'Güncellenmiş Başlık' }
      },
      {
        method: 'DELETE',
        path: '/wp/v2/comments/15',
        body: { force: true }
      },
      {
        method: 'GET',
        path: '/wp/v2/users/me'
      }
    ]
  };

  try {
    const response = await fetch(restUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-WP-Nonce': wpNonce
      },
      body: JSON.stringify(batchData)
    });

    const result = await response.json();
    console.log('Batch Yanıtı:', result);
  } catch (error) {
    console.error('Batch işlemi sırasında hata oluştu:', error);
  }
}

sendWordPressBatch();

3. PHP (cURL) Kullanarak Sunucudan Sunucuya Batch İstek

Eğer başka bir PHP uygulamasından veya mikroservisten WordPress sitenize veri aktarıyorsanız cURL kullanarak batch istek atabilirsiniz:

$api_url = 'https://ornek-siteniz.com/wp-json/wp/v2/batch';
$app_password = 'abcd efgh ijkl mnop'; // WordPress Uygulama Şifresi
$username = 'admin_kullanici';

$payload = [
    'requests' => [
        [
            'method' => 'GET',
            'path'   => '/wp/v2/posts?per_page=2'
        ],
        [
            'method' => 'GET',
            'path'   => '/wp/v2/tags?per_page=2'
        ]
    ]
];

$ch = curl_init($api_url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Basic ' . base64_encode($username . ':' . $app_password)
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

Batch İsteklerinde Darboğazlar ve Sunucu Tarafı Optimizasyonu

Batch istekleri ağ seviyesindeki latency problemini çözse de bilinçsiz kullanıldığında sunucu tarafında ciddi kaynak tüketim krizlerine (Memory Leak, CPU spiking) yol açabilir. Tek bir istek içinde 100 farklı ağır veri sorgusunu çalıştırmak PHP belleğini (memory_limit) tüketebilir veya MySQL veritabanını kilitleyebilir.

1. Maksimum Batch İstek Sınırını Yönetmek

WordPress varsayılan olarak bir batch paketinde en fazla 25 alt isteğe izin verir. Bu sınır sunucunun çökmesini engellemek için koyulmuş bir emniyet sibobudur. Güçlü bir sunucu altyapısına sahipseniz veya aksine kısıtlı bir paylaşımlı hosting kullanıyorsanız bu limiti rest_get_max_batch_size filtresi ile değiştirebilirsiniz:

// wp-content/themes/tema-adi/functions.php veya özel eklentiye ekleyin
add_filter('rest_get_max_batch_size', function($max_size) {
    // Sınırı 50'ye yükselt veya düşük donanımlı sunucuda 10'a düşür
    return 50;
});

2. Veritabanı ve Nesne Önbellekleme (Object Cache)

Toplu istekler sırasında veritabanına atılan N+1 sorgu problemi katlanarak büyür. Örneğin batch içinde 20 farklı yazının detayını istediğinizde, WordPress her bir dahili dispatch için veritabanına tekrarlayan sorgular atabilir.

Bu sorunu aşmak için Redis veya Memcached tabanlı bir Persistent Object Cache çözümü mutlaka aktif edilmelidir. WordPress object cache aktif olduğunda WP_Query veritabanına gitmek yerine RAM üzerinden sonuçları getirir ve batch süresini milisaniyeler seviyesine çeker. Genel site performansınızı artırmak için WordPress Site Hızlandırma Rehberi: Adım Adım Performans Artırma başlıklı yazımızı inceleyebilirsiniz.

3. PHP Execution Time ve Bellek Ayarları

Büyük ölçekli veri aktarımlarında php.ini üzerindeki max_execution_time ve memory_limit değerleri yetersiz kalabilir. Nginx veya Apache yapılandırmanızda timeout sürelerini kontrol etmeli, batch işlemlerini küçük parçalar halinde (chunking) göndermelisiniz. Örneğin 1000 ürünü güncelleyecekseniz 25'erli paketler halinde 40 farklı batch isteği atmanız en güvenli yoldur.

Sık Yapılan Hatalar ve Çözüm Stratejileri

WordPress REST API Batch mimarisini entegre ederken geliştiricilerin sıklıkla düştüğü bazı hatalar şunlardır:

Hata 1: Yanlış Yetkilendirme Kullanımı

Alt istekler ana batch isteğinin güvenlik bağlamını mirası olarak devralır. Ana batch isteğinde geçerli bir X-WP-Nonce veya Authorization başlığı yoksa, paket içindeki tüm POST veya PUT istekleri 401 Unauthorized hatası döndürür. Alt isteklere bireysel olarak yetkilendirme başlığı eklemek yerine ana isteğin başlığına yetki eklemelisiniz.

Hata 2: Bağımlı İsteklerin Yanlış Sıralanması

Bir kategorinin oluşturulması ve hemen ardından o kategoriye bir yazının eklenmesi gibi birbirine bağımlı işlemleri tek bir batch paketi içinde atarken dikkatli olunmalıdır. Yanıt henüz birinci işlem bitmeden ikincisine geçebileceğinden veya birinci işlem hata aldığında ikinci işlem geçersiz kategori ID'sine başvuracağından işlemler başarısız olabilir. Bağımlı mantıksal zincirleri ayrı isteklerde yönetmek veya validation: require-all-validate kullanmak mantıklıdır.

Hata 3: Yanıt Boyutunun Aşırı Büyümesi

Batch yanıtında dönen gövde devasa boyutlara ulaşabilir. Sadece ihtiyacınız olan alanları istemek için WordPress REST API'nin _fields parametresinden faydalanın:

{
  "method": "GET",
  "path": "/wp/v2/posts?_fields=id,title,slug,date"
}

Bu yöntem ağ üzerinden taşınan JSON payload'ını %80 oranında küçültecektir.

WordPress REST API Batch ve GraphQL Karşılaştırması

Sistem mimarinizi tasarlarken batch istekler ile GraphQL (WPGraphQL) arasında kararsız kalabilirsiniz. İki teknolojinin karar kriterleri şu şekildedir:

• Karmaşıklık: REST API Batch istekleri varsayılan WordPress çekirdeğinde hazırdır, ek bir eklenti kurulumu gerektirmez. WPGraphQL ise sitenize ek bir eklenti yüklemenizi ve yeni bir sorgu dili öğrenmenizi gerektirir.
• Veri Seçiciliği: GraphQL, istemcinin tam olarak ihtiyaç duyduğu veriyi seçmesini doğal olarak sağlar. REST API'de ise _fields parametresi kullanılmazsa gereksiz veri çekilebilir.
• Mevcut Ekosistem Entegrasyonu: Mevcut bir REST API altyapınız varsa batch sistemine geçmek birkaç saatlik bir istemci kod revizyonu ile tamamlanır.

Sonuç ve Sonraki Adımlar

WordPress REST API Batch İstekleri, mobil uygulamalarda, headless projelerde ve karmaşık yönetim panellerinde ağ gecikmesini optimize etmenin en etkili yollarından biridir. Birden fazla HTTP isteğini tek paket halinde sunucuya ileterek hem kullanıcı deneyimini hızlandırabilir hem de sunucu ağ kilitlenmelerinin önüne geçebilirsiniz.

Uygulamanızda bu yapıyı hayata geçirmek için ilk adım olarak API çağrılarınızı gözden geçirin. Ardışık atılan istekleri tespit edip bunları JavaScript tarafında bir batch paketine dönüştürün. Sunucu tarafında ise Redis object cache kullanarak ve rest_get_max_batch_size değerini sunucu kapasitenize göre ayarlayarak kusursuz bir performans elde edin.