WooCommerce çift API: GraphQL çekirdeğe geliyor (10.9)

Birkaç yılda bir, ilk bakışta “bir API daha” gibi görünen bir WooCommerce haberi düşer önümüze. Bunları yavaş okumayı öğrendim. Çoğu zaman bir iki uç noktanın eklenmesinden ibarettir. Bazen de önümüzdeki on yılın entegrasyonlarının nasıl kurulacağını baştan tanımlar. Bu haber ikinci kategoriden ve yeterince özel REST eklentisi yazmış birinden dinlemenizi tercih ederim.

Yıllardır “WooCommerce üzerine gerçek bir GraphQL katmanı nasıl kurulur?” sorusunun dürüst cevabı şuydu: WPGraphQL üzerine WooGraphQL kur, bakım borcunu kabul et ve uç durumların dayanmasını um. O yığın bugüne kadar büyük iş çıkardı, hâlâ da çıkarıyor. Ama Woo’nun yanında duruyordu, içinde değil. WooCommerce 10.9 ile bu denklem değişiyor — sessizce, deneysel biçimde ve başsız (headless) mağaza kuran her ajansın dikkat etmesi gereken koşullarla.

Bu hafta öneriyi ve geliştirici belgelerini okudum, sonra iki başsız müşterimiz için göç senaryosunun nasıl görüneceğini kâğıda döktüm. Aşağıda gerçekte ne çıkıyor, ne çıkmıyor ve pazartesi sabahı ne yapardım onları anlatıyorum.

Gerçekten yeni olan ne

WooCommerce ekibi 4 Haziran’da Introducing the WooCommerce dual API yazısını yayımladı ve WooCommerce 10.9 ile gelen “kod öncelikli API mimarisini” tanıttı. Beta 1 sürümü 8 Haziran’da yayımlandı, son sürüm ise 23 Haziran 2026’ya planlandı. Altını çizmeye değer kısım takvim değil — yapının kendisi.

Çift API üç parçadan oluşuyor. Birincisi, otoriter bir kod API’si: PHP nitelikleriyle (attributes) süslenmiş düz PHP sınıfları. Çalıştırılabilir sınıflar komut desenini izliyor, veri sınıfları ise DTO görevi görüyor. İkincisi, bu kod API’sini bire bir yansıtan, otomatik üretilen bir GraphQL API’si: komutlar query ve mutation oluyor, DTO’lar ise input ve output tiplerine dönüşüyor. Üçüncüsü, GraphQL şemasını geliştirme zamanında PHP’den üreten bir build betiği. Böylece iki taraf birbirinden uzaklaşmıyor.

Resmi belgeler kapsam ve kararlılık konusunda net: bu özellik “deneysel ve bir kavram kanıtı”, Automattic\WooCommerce\Api ad alanı altındaki her şey herhangi bir sürümde geriye dönük uyumsuz biçimde değişebilir ve özellik bir bayrağın (feature flag) arkasında. Şu komutla açılıyor: wp option update woocommerce_feature_dual_code_graphql_api_enabled yes. 10.9’daki yüzey alanı bilinçli olarak küçük tutulmuş — ürünler ve kuponlar — yani bir mağazayı buna bağlamadan deneme şansınız var.

İki kısıt daha önemli. Çift API PHP 8.1 veya üstünü gerektiriyor; çünkü PHP nitelikleri, enum’lar ve adlandırılmış argümanlar üzerine kurulu. Ve eklentilerin aynı numarayı yapabilmesi için tasarlanıyor — kendi kod sınıflarınızı tanımlıyorsunuz, build betiğini çalıştırıyorsunuz ve eklentiniz kendi GraphQL yüzeyini Woo şemasının geri kalanına bağlanacak şekilde paketliyor. Çoğu geliştiricinin ilk okumada gözden kaçıracağı ama dördüncü çeyrekte en çok önemseyeceği nokta tam burası.

Bağlam için: bu özellik, Automattic’in Radical Speed Month girişiminin daha kalıcı çıktılarından biri. Nisan–Mayıs ayında çalışanları özerk ekiplere ayırıp dört yüzden fazla deney üretmelerini sağlayan inisiyatifin meyvesi. O deneylerin çoğu oyuncak gibiydi. Bu öyle değil.

WordPress ve WooCommerce dünyası için neden önemli

Üç şey değişiyor; en kısa sürede hissedeceğiniz sıraya göre.

Başsız mağazalar artık birinci taraf bir cevaba sahip. Şimdiye kadar her başsız Woo projesi bir seçim yapmak zorundaydı: REST API ve Store API’ye yaslan ve gevezeliğin bedelini öde, ya da WPGraphQL artı WooGraphQL artı bir bakım planını üst üste yığ. Her ikisi de meşru. Hiçbiri Woo çekirdek ekibinin sahip olduğu bir şey değil. Mağazayı çalıştıran PHP’den üretilen yerel bir GraphQL yüzeyi, “üçüncü taraf şema çekirdekten uzaklaştı mı?” sınıfındaki bir grup hatayı ortadan kaldırıyor. Üçüncü taraf yığını yok etmiyor — WPGraphQL bugün çok daha olgun — ama Automattic’in GraphQL oyununda artık doğrudan bir payı olduğunu gösteriyor. Bu da çoktan olması gereken bir şeydi.

Eklenti yazarları aklı başında bir yeni sözleşme kazanıyor. Bir Woo eklentisi sürdürüyorsanız bu dansı biliyorsunuz: iş mantığını yaz, action ve filter’larla dışa aç, sonra paralel bir REST denetleyicisi yaz, sonra paralel belgeler yaz, sonra ikisi birbirinden uzaklaştığında çıkan sorunlara yetiş. Çift API’nin önerisi şu: “kod sınıfını niteliklerle bir kez yaz, API yüzeyini bedavaya al.” Kutlama yapmadan önce bunu üretimde test etmek istediğim kısım; ama tasarım niyeti doğru.

Yapay zekâ ajanları tipli ve incelenebilir bir yüzeye kavuşuyor. Bu, kimsenin manşete çekmediği ama gerçek olan kalem. Woo ekibi bir süredir ajan dostu ticarete doğru ilerliyor — bu ayın başındaki Abilities API genişlemesi, ondan önceki MCP çalışmaları. Tipli ve içe bakım (introspection) destekli bir GraphQL şeması, bir LLM araç çağırma katmanının tam da tüketmek isteyeceği şey. İki duyuruyu yan yana okuyun, strateji temiz çıkıyor: üst seviye niyet için yetenekler, asıl iş için tipli API.

Bunun değiştirmediği bir şey var: mevcut REST ve Store API kodunuz çalışmaya devam ediyor. Çift API eklemeli bir özellik. 10.9’da hiçbir şey kullanım dışı bırakılmıyor.

Yerinizde olsam (ya da olmasam) ne yapardım

Üretimde bir WooCommerce mağazası işletiyorsanız, 10.9 ile hiçbir şey yapmayın. Duyuruyu okuyun, belgeleri yer imine ekleyin, yolunuza devam edin. “Deneysel, geriye dönük uyum garantisi yok, özellik bayrağı arkasında, yalnızca PHP 8.1+” — WooCommerce ekibinin üç farklı şekilde “bunu Cuma günü yayına almazsınız” dediği bir cümle.

Bir Woo eklentisi geliştiriyor ya da sürdürüyorsanız, PHP 8.2 üzerinde bir hazırlık (staging) sitesi açıp özellik bayrağını etkinleştirmek ve ürün ile kupon kod API’lerinin nasıl süslendiğine bakmak için doğru an. Bugün öğreneceğiniz desenler, bir müşterinizin “eklentiniz neden GraphQL şemasında değil?” diye ticket açtığı gün desteklemek zorunda kalacağınız desenler. O konuşmanın altı ay öncesinde olmak, iki hafta öncesinde olmaktan iyidir.

Önümüzdeki iki çeyrekte yeni bir başsız mağaza planlıyorsanız, ben yine Store API üzerine — gerekirse WPGraphQL ve WooGraphQL ile — kurardım. Çift API kötü olduğu için değil — iyi tasarlanmış — ama “kavram kanıtı, sadece ürünler ve kuponlar” üç yıl ayakta tutmak istediğiniz bir lansman için sağlam bir temel değil. 10.10 ve 11.0’da neyin geleceğini izleyin. Yüzey alanı büyük API yeniden yazımları olmadan siparişlere, müşterilere ve aboneliklere doğru genişlerse, konuşma tersine döner.

Ve birinin WooCommerce ile sunucu tarafı ticaret platformlarını “gerçek bir GraphQL API’niz var mı?” satırı üzerinden karşılaştırdığı bir kurumsal satın alma toplantısındaysanız — geçen aydan daha iyi bir cevabınız var. Bitmiş bir cevap değil ama üçüncü taraf bahsi değil, çekirdek ekipten gelen güvenilir bir yol haritası. Bu, toplantıyı değiştirir.

Yirmi yıllık örüntüye güveniyorum: WordPress ve WooCommerce nadiren ilk varan olur, ama yönetişimle, eklenti ekosistemiyle ve üzerine iş kurulabilecek bir sözleşmeyle varır. Çift API, GraphQL çağı için o sözleşmenin erken sürümü. Takip etmeye değer. Üzerine bahis oynamaya henüz değil.