WooCommerce Dual API Eklentiye Dönüşüyor: Headless E-Ticarette Yeni Mimari Yaklaşım

Modern e-ticaret ekosisteminde web sitelerinin hızı, esnekliği ve API tabanlı mimarilere uyumu, dijital operasyonların başarısını doğrudan belirlemektedir. Özellikle headless (ayrık) e-ticaret projelerinde REST API ve GraphQL arasındaki teknik tercihler, hem geliştirici deneyimini (DX) hem de son kullanıcıya sunulan Core Web Vitals metriklerini kritik düzeyde etkiler. WooCommerce mühendislik ekibinin WooCommerce 10.9 sürümünde duyurduğu deneysel 'Dual API' mimarisi, WooCommerce 11.2 itibarıyla çekirdekten (core) çıkarılarak bağımsız bir eklenti haline getirildi.

Bu stratejik hamle, WordPress çekirdeğinin şişmesini (code bloat) engellerken, modern API geliştirme pratiklerini benimseyen yazılım ekiplerine daha esnek ve çevik bir geliştirme döngüsü sunuyor. Bu teknik analizde; WooCommerce Dual API'nin evrimini, PHP sınıflarından otomatik GraphQL şeması üretiminin perde arkasını ve headless mimarilerdeki teknik SEO ile performans etkilerini ayrıntılı olarak inceliyoruz.

WooCommerce Dual API Nedir ve Neden Ortaya Çıktı?

Geleneksel WooCommerce altyapısı, yıllardır WordPress REST API motorunu temel alarak hizmet vermektedir. REST mimarisi geniş bir uyumluluk ve olgun bir ekosistem sunsa da modern headless mimarilerde iki büyük zorluğu beraberinde getirir: Aşırı veri çekme (over-fetching) ve yetersiz veri çekme (under-fetching). Karmaşık bir e-ticaret ürün detay sayfasında (PDP) birden fazla REST uç noktasına istek atmak ağ gecikmesini (latency) artırır ve özellikle mobil cihazlarda 'First Meaningful Paint' ve LCP (Largest Contentful Paint) değerlerini olumsuz etkiler.

Dual API, kod-öncelikli (code-first) bir yaklaşım benimser. Geliştiricilerin saf PHP sınıfları ve tipleri tanımlamasını şart koşar; motor, bu PHP modellerini çalışma zamanında analiz ederek hem standart veri yapılarını hem de otomatik GraphQL uç noktalarını türetir. Böylece geliştiricilerin WPGraphQL gibi harici şema katmanlarını her veri türü için sıfırdan el yordamıyla kaydetme ihtiyacı ortadan kalkar.

Kritik Mimari Değişim: WooCommerce 11.2 öncesinde doğrudan çekirdek içinde yer alan ürün ve kuponlara ait konsept kanıtı (proof-of-concept) uç noktaları tamamen kaldırılmıştır. Yeni yapı, geliştiricilerin kendi uç noktalarını inşa etmesi için bir altyapı motoru sağlamakta, hazır şemalar yerine modüler geliştirme imkânı tanımaktadır.

Çekirdekten Eklentiye Geçişin Teknik Sebepleri

Bir API motorunun çekirdek bünyesinde barındırılması, her hata düzeltmesi, şema güncellemesi veya performans iyileştirmesinin WooCommerce ana sürüm takvimine (major release cycle) bağımlı kalmasına yol açar. Mühendislik ekibinin Dual API'yi bağımsız bir GitHub deposu ve WordPress eklentisi olarak konumlandırması şu avantajları doğurur:

• Bağımsız Sürüm Döngüsü: Çekirdek yayın takvimini beklemeden haftalık veya anlık yamalarla kütüphaneyi modernize edebilme.
• Çekirdek Optimizasyonu: Headless veya Dual API kullanmayan yüz binlerce standart monolitik WooCommerce mağazasının gereksiz PHP sınıflarını belleğe yüklemesini engelleme.
• Deneysel Geliştirme Güvenliği: Automattic\WooCommerce\Api ad alanı altındaki sınıfların geriye dönük uyumluluk (backward compatibility) kısıtlaması olmadan hızla evrilebilmesi.

REST API, WPGraphQL ve Dual API Karşılaştırması

Aşağıdaki teknik değerlendirme tablosu, WooCommerce ekosistemindeki mevcut veri erişim paradigmalarını karşılaştırmaktadır:

Yeni Dual API Mimarisine Geçiş ve Entegrasyon

Dual API'yi kendi özel eklentilerinde bir GraphQL uç noktası sağlamak amacıyla kullanacak ekipler için gereksinimler değişti. Projeler artık en az WooCommerce 11.2 ve PHP 8.1 çalışma zamanına ihtiyaç duymaktadır.

1. Eklenti Bağımlılık Bildirimi

Özel eklentinizin ana başlık bloğunda WordPress 6.5 ile tanıtılan Requires Plugins yönergesini kullanmanız gerekmektedir:

/**
 * Plugin Name: Custom Headless Commerce Extension
 * Description: Dual API motorunu kullanarak headless uç noktaları sunan özel servis.
 * Version: 1.0.0
 * Requires PHP: 8.1
 * Requires Plugins: woocommerce, woocommerce-dual-api
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

2. GraphQL Uç Noktası Tanımlama

Dual API kurulu ve etkin olduğunda, eklentiniz Automattic\WooCommerce\Api\Infrastructure\Main sınıfı üzerinden kendi GraphQL şemasını ve bağlamını sisteme tanıtır. Aşağıdaki örnek, uç noktanın modern ve güvenli bir şekilde nasıl kaydedileceğini göstermektedir:

use Automattic\WooCommerce\Api\Infrastructure\Main as DualApiMain;

add_action( 'plugins_loaded', static function () {
    // Dual API motorunun aktif olup olmadığını kontrol et
    if ( method_exists( DualApiMain::class, 'register_graphql_endpoint' ) ) {
        DualApiMain::register_graphql_endpoint(
            __DIR__,
            'wc-store',
            '/graphql/custom-store'
        );
    }
} );

Bu kod bloğu, eklentinizin dizinini tarayarak tanımlı PHP sınıflarından /graphql/custom-store yolunda bir sorgulama şeması inşa eder.

Teknik SEO ve Headless Performans Analizi

Headless WooCommerce mimarilerinde Next.js, Nuxt veya Astro gibi modern JavaScript kütüphaneleri tercih edildiğinde, API katmanının stabilitesi ve veri transfer maliyeti doğrudan teknik SEO başarısını tayin eder. REST API kullanımında ürün detay sayfaları render edilirken oluşan ağ darboğazları TTFB (Time to First Byte) sürelerini uzatır.

SSR ve Edge Cache Avantajı

Dual API'nin sağladığı GraphQL şemaları, Server-Side Rendering (SSR) veya Incremental Static Regeneration (ISR) pipeline'larında tam olarak ihtiyaç duyulan meta alanları (fiyat, stok durumu, schema.org JSON-LD verileri) tek bir ağ çağrısıyla çeker. Bu durum:

• Sunucu yanıt sürelerini (TTFB) 200ms bareminin altına indirmeye yardımcı olur.
• Googlebot'un crawl bütçesini (crawl budget) tüketmeden sayfaların hızlı indekslenmesini sağlar.
• JSON payload boyutunu %60'a varan oranda küçülterek LCP (Largest Contentful Paint) skorlarını iyileştirir.

Ancak, Dual API'nin henüz deneysel statüde olması nedeniyle production ortamındaki SEO kritik sitelerde doğrudan kullanılmaması, bunun yerine staging ortamlarında geleceğin headless mimarilerini test etmek adına değerlendirilmesi hayati önem taşır.

Geliştiriciler İçin Stratejik Yol Haritası

1. Eski POC Kodlarını Temizleyin: WooCommerce 10.9-11.1 aralığındaki dahili ürün ve kupon Dual API uç noktalarına bel bağlayan yapılar WooCommerce 11.2 ile çalışmayacaktır. Bu çağrıları kaldırın.
2. Modern PHP 8.1+ Tiplerine Geçin: Dual API motoru, PHP'nin güçlü tip sistemine dayanır. Sınıflarınızda dönüş tiplerini (return types) ve Typed Properties özelliklerini eksiksiz kullanın.
3. Geri Bildirim Döngüsüne Katılın: WooCommerce geliştirici topluluğu, motorun çekirdeğe kararlı (stable) bir biçimde dönüp dönmeyeceğini GitHub tartışmalarındaki geliştirici geri bildirimlerine göre belirleyecektir.

Kaynak: WooCommerce Devs - https://developer.woocommerce.com/2026/09/28/experimental-dual-api-plugin/