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

🇬🇧 English: Read this in English →

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 dinlemeni 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 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ı tanımlıyorsun, build betiğini çalıştırıyorsun ve eklentin 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ğin 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 bu dansı biliyorsun: 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 oku, 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 kodun çalışmaya devam ediyor. Çift API eklemeli bir özellik. 10.9’da hiçbir şey kullanım dışı bırakılmıyor.

Bugün başsız kuruyorsan hangi katman

“Peki şimdi ne kullanayım?” sorusunun net bir cevabı var, çünkü üç seçenek üç farklı olgunlukta:

• Store API (+ gerekiyorsa REST): bugün üretime çıkacak bir mağaza kuruyorsan varsayılan tercih bu. Sepet, ödeme, oturum — hepsi olgun ve destekli. Sıkıcı ama üç yıl ayakta kalır.
• WPGraphQL + WooGraphQL: GraphQL’i bugün istiyor ve bakım borcunu kabullenmeye razıysan. Ekosistem olgun, topluluk büyük; sadece Woo çekirdeğinin sahip olmadığını unutma.
• Çift API: şimdilik yalnızca öğrenmek, prototiplemek ve yön belirlemek için. Ürünler ve kuponlarla oyna, desenleri öğren — ama canlı bir lansmanın temeline koyma. Bu, 10.10 ve 11.0’ı izleyip karar vereceğin bir yatırım.

Ben olsam bugünün mağazasını Store API üzerine, yarının bahsini çift API üzerine kurardım — ve ikisini karıştırmadan, hangisinin hangi işi yaptığını müşteriye baştan net söylerdim.

Yerinde olsam (ya da olmasam) ne yapardım

Üretimde bir WooCommerce mağazası işletiyorsan, 10.9 ile hiçbir şey yapma. Duyuruyu oku, belgeleri yer imine ekle, yoluna devam et. “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” dediği bir cümle.

Bir Woo eklentisi geliştiriyor ya da sürdürüyorsan, 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ğin desenler, bir müşterinin “eklentin neden GraphQL şemasında değil?” diye ticket açtığı gün desteklemek zorunda kalacağın 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, 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ğin bir lansman için sağlam bir temel değil. 10.10 ve 11.0’da neyin geleceğini izle. 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 — geçen aydan daha iyi bir cevabın 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.