GraphQL Nedir? REST API Farkları ve WPGraphQL Kurulum Rehberi

GraphQL nedir sorusu, modern web ve mobil uygulama geliştirme ekosisteminde istemci ile sunucu arasındaki veri alışverişini kökten değiştiren açık kaynaklı bir veri sorgulama dili ve çalışma zamanı (runtime) şeklinde yanıtlanabilir. Geleneksel API Nedir? REST API Temelleri ve Kullanımı yaklaşımında sunucunun belirlediği sabit veri yapılarına bağımlı kalırken, GraphQL sayesinde istemci (client) tam olarak ihtiyaç duyduğu veriyi tanımlar ve sunucudan sadece bu veriyi talep eder. 2012 yılında Meta (Facebook) tarafından dahili mobil uygulamalardaki ağ performansını optimize etmek amacıyla geliştirilen GraphQL, 2015 yılında açık kaynak haline getirilmiş ve günümüzde modern yazılım mimarilerinin vazgeçilmez bir standardına dönüşmüştür.

Web geliştirme dünyası 2026 yılı itibarıyla tamamen modüler, microservices tabanlı ve "Headless" mimarilere kaymış durumdadır. Bu dönüşümde, monolitik sistemlerdeki gereksiz veri yükünü (over-fetching) ve ardışık istek zorunluluklarını (under-fetching) ortadan kaldıran GraphQL, geliştirici deneyimini (DX) en üst seviyeye taşır. Bu rehberde GraphQL mimarisinin detaylarını, REST API ile arasındaki farkları ve WordPress sitenizi bir Headless altyapıya dönüştürmek için WPGraphQL kurulumunu adım adım inceleyeceğiz.

GraphQL Nedir ve Nasıl Çalışır?

GraphQL, klasik HTTP mimarilerindeki çoklu endpoint (uç nokta) karmaşasını tek bir endpoint altında toplar. Uygulamanız hangi veriye ihtiyaç duyuyorsa, bunu standart bir JSON yapısına benzer bir sorgu metniyle sunucuya bildirir. Sunucu, gelen bu sorguyu analiz eder ve tip sistemine (Schema) göre doğrulayarak tıpatıp aynı hiyerarşik yapıda bir JSON yanıtı döner.

GraphQL mimarisinin temelini üç ana kavram oluşturur:

• Query (Sorgu): Veritabanından veri okumak için kullanılan read-only isteklerdir.
• Mutation (Mutasyon): Veri eklemek, güncellemek veya silmek (CRUD) için kullanılan yazma istekleridir.
• Subscription (Abonelik): WebSocket üzerinden sunucudan istemciye gerçek zamanlı (real-time) veri akışı sağlayan dinleyicilerdir.

GraphQL mimarisinde sunucudaki verilerin yapısını Schema (Şema) ve Type System (Tip Sistemi) tanımlar. Örneğin bir blog yazısını ve yazarını getirmek için istemci tarafından atılan basit bir GraphQL sorgusu şu şekildedir:

query GetSinglePost {
  post(id: "101") {
    title
    date
    author {
      name
      email
    }
  }
}

Bu sorgunun sunucudan döneceği yanıt ise eksiksiz olarak şu biçimdedir:

{
  "data": {
    "post": {
      "title": "GraphQL Nedir?",
      "date": "2026-08-12",
      "author": {
        "name": "Ahmet Yılmaz",
        "email": "ahmet@webteknoloji.net"
      }
    }
  }
}

Görüldüğü üzere, istek yapısı ile gelen yanıt yapısı birebir örtüşür. İstemci author altından avatar alanını istemediyse, sunucu bu veriyi işlemek ve ağ üzerinden taşımakla uğraşmaz.

GraphQL vs REST API: Mimari Farklar ve Karşılaştırma

REST mimarisi yıllardır web hizmetlerinin temeli olsa da, karmaşıklaşan istemci ihtiyaçları karşısında bazı sınırlılıklara sahiptir. Karar verme aşamasındaki yazılımcılar için WordPress REST API Kullanım Rehberi: Özel Endpoint Oluşturma süreçlerinde karşılaşılan zorluklar, GraphQL'in neden tercih edildiğini net bir şekilde ortaya koyar.

1. Over-fetching ve Under-fetching Problemi

Over-fetching (Aşırı Veri Çekme): REST API kullanırken /api/users/1 endpoint'ine istek attığınızda, kullanıcı adı hariç telefon numarası, adres, profil geçmişi gibi 30 farklı alan dönebilir. Mobil cihazlarda bu durum yüksek veri tüketimi ve yavaş açılış süreleri anlamına gelir.

Under-fetching (Yetersiz Veri Çekme): Bir kullanıcının son yazılarını ve bu yazıların yorumlarını ekranda göstermek için REST mimarisinde sırasıyla /users/1, /users/1/posts ve /posts/5/comments endpoint'lerine ayrı ayrı HTTP istekleri atmanız gerekebilir. GraphQL ise bu üç farklı veri kaynağını tek bir istekte (single request) birleştirerek istemciye sunar.

2. Endpoint Yapısı ve Esneklik

REST API'de kaynaklar (resources) URI'lar üzerinden yönetilir (/api/v1/products, /api/v1/orders). Her yeni veri türü için yeni bir uç nokta oluşturulmalı veya var olanlar güncellenmelidir. GraphQL'de ise varsayılan olarak yalnızca tek bir endpoint bulunur (genellikle /graphql). Tüm sorgu ve mutasyonlar bu tek uç noktaya HTTP POST istekleri olarak gönderilir.

3. Tip Güvenliği ve Otomatik Dokümantasyon

GraphQL güçlü bir tip sistemine (Strongly Typed Schema) sahiptir. String, Int, Boolean, ID ve özel oluşturulan nesne tipleri sayesinde API geliştirilirken hatalar derleme anında tespit edilir. Ayrıca Schema Yapısı sayesinde GraphiQL veya Altair gibi IDE araçları üzerinden sunucudaki tüm alanlar otomatik olarak dokümante edilir.

Karar Kriteri: Eğer basit CRUD işlemleri yapan, önbellekleme mekanizmalarını HTTP seviyesinde (CDN tabanlı) yönetmek istediğiniz geleneksel bir projeniz varsa REST API halen mükemmel bir seçenektir. Ancak çoklu platformlara (iOS, Android, Web) hizmet veren, karmaşık ilişkisel verileri yoğun olarak kullanan modern web uygulamalarında GraphQL belirgin bir üstünlük sağlar.

WPGraphQL Nedir? WordPress'i Headless Mimarisine Taşıma

WordPress, dünya üzerindeki web sitelerinin büyük bir kısmına güç veren devasa bir içerik yönetim sistemidir. Ancak günümüzde monolith yapılar yerine frontend tarafında Next.js, React, Vue veya Nuxt kullanan modern mimariler tercih edilmektedir. Progressive Web App (PWA) Nedir? Web Siteleri İçin PWA Kurulum Rehberi hazırlarken headless bir CMS yapısı kullanmak, hız ve kullanıcı deneyimi açısından muazzam avantajlar sunar.

WPGraphQL, WordPress sitenize ücretsiz ve açık kaynaklı bir GraphQL sunucusu ekleyen eklentidir. WordPress veritabanınızdaki tüm yazıları, sayfaları, özel içerik tiplerini (CPT), kategorileri, kullanıcıları ve ortam kütüphanesini anında bir GraphQL şemasına dönüştürür. Böylece WordPress'i sadece bir içerik yönetim paneli (Headless CMS) olarak kullanabilir, frontend tarafını tamamen bağımsız bir teknolojide geliştirebilirsiniz.

Adım Adım WPGraphQL Kurulum ve Kullanım Rehberi

WordPress sitenizi GraphQL gücüyle donatmak oldukça basittir. Sırasıyla aşağıdaki adımları uygulayarak geliştirmeye başlayabilirsiniz.

Adım 1: WPGraphQL Eklentisini Yükleme

WordPress yönetim panelinize (wp-admin) giriş yapın.

Eklentiler > Yeni Eklenti Ekle sekmesine gidin.

Arama çubuğuna WPGraphQL yazın.

Jason Bahl ve WPGraphQL topluluğu tarafından geliştirilen eklentiyi bulun, Hemen Yükle ve ardından Etkinleştir butonuna tıklayın.

Eklenti aktifleştirildiğinde sol menüye GraphQL sekmesi eklenecek ve varsayılan GraphQL endpoint'iniz https://siteniz.com/graphql olarak yayına girecektir.

Adım 2: GraphiQL IDE ile İlk Sorguyu Çalıştırma

WPGraphQL eklentisi içerisinde dahili bir sorgu editörü olan GraphiQL IDE ile birlikte gelir. Yönetim panelinizdeki sol menüden GraphQL > GraphiQL IDE sekmesine tıklayın.

Editör ekranına aşağıdaki sorguyu yapıştırın ve üstteki Oynat (Execute Query) butonuna basın:

query GetRecentPosts {
  posts(first: 5) {
    nodes {
      id
      title
      slug
      date
      excerpt
      featuredImage {
        node {
          sourceUrl
          altText
        }
      }
    }
  }
}

Sağ taraftaki panoda WordPress veritabanınızdaki son 5 yazının başlıkları, özetleri ve öne çıkarılan görsel bağlantıları JSON formatında anında görüntülenecektir.

Adım 3: Özel Post Tiplerini (Custom Post Types) GraphQL Şemasına Ekleme

WordPress sitenizde kod ile veya CPT UI gibi eklentilerle oluşturduğunuz özel yayın tipleri varsayılan olarak GraphQL şemasında görünmeyebilir. Özel bir post tipini GraphQL'e dahil etmek için register_post_type fonksiyonuna show_in_graphql, graphql_single_name ve graphql_plural_name parametrelerini eklemeniz gerekir.

Temanızın functions.php dosyasına veya özel bir eklentiye ekleyebileceğiniz örnek PHP kodu:

function wtk_register_portfolio_cpt() {
    $args = array(
        'labels'             => array('name' => 'Portfolyo'),
        'public'             => true,
        'has_archive'        => true,
        'show_in_rest'       => true,
        'show_in_graphql'    => true, // WPGraphQL Desteğini Aç
        'graphql_single_name' => 'portfolioItem',
        'graphql_plural_name' => 'portfolioItems',
        'supports'           => array('title', 'editor', 'thumbnail')
    );
    register_post_type('portfolio', $args);
}
add_action('init', 'wtk_register_portfolio_cpt');

Bu kodu ekledikten sonra GraphiQL IDE ekranında portfolioItems şeklinde yeni bir sorgu alanının otomatik olarak oluştuğunu göreceksiniz.

Adım 4: Frontend (React / Next.js) Tarafında Veri Çekme

Headless WordPress mimarisinde istemci tarafında verileri çekmek için karmaşık kütüphaneler kurmak zorunda değilsiniz. Standart JavaScript fetch API kullanarak WPGraphQL'den veri çekmek son derece kolaydır.

Aşağıdaki kod örneği, bir Next.js veya React bileşeninde WPGraphQL endpoint'inden veri çekmeyi gösterir:

async function getWordPressPosts() {
  const query = `
    query GetPosts {
      posts(first: 10) {
        nodes {
          id
          title
          slug
        }
      }
    }
  `;

  const res = await fetch('https://siteniz.com/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query }),
    next: { revalidate: 60 } // Next.js ISR Önbellekleme Ayarı
  });

  const { data } = await res.json();
  return data.posts.nodes;
}

GraphQL Kullanırken Sık Yapılan Hatalar ve Performans İpuçları

GraphQL esnekliği ve gücüyle öne çıksa da, yanlış mimari kararlar verim kaybına neden olabilir.

1. N+1 Sorgu Problemi ve Çözümü

GraphQL sorgularında ilişkisel veriler çekilirken (örneğin 10 yazının ve her yazının yazarının ayrı ayrı çekilmesi) veritabanına 1 + 10 = 11 adet sorgu atılabilir. Bu durum N+1 problemi olarak adlandırılır. WPGraphQL arka planda DataLoader kalıbını kullanarak sorguları toplu hale getirir (batching) ve bellek içi önbellekleme yaparak veritabanı yükünü minimize eder.

2. Karmaşık Sorgu ve Derinlik Sınırlamaları (Query Depth Limit)

İstemcilerin sonsuz iç içe geçen sorgular göndermesi sunucuyu kilitleyebilir. Örneğin: post -> author -> posts -> author -> posts...

Bu tarz kötü niyetli veya hatalı sorguların önüne geçmek için üretim ortamında sorgu derinliği (Query Depth) ve sorgu karmaşıklığı (Query Complexity) sınırlamaları getirilmelidir. WPGraphQL Smart Cache gibi araçlarla bu güvenlik kontrolleri sağlanabilir.

3. Önbellekleme (Caching) Zorlukları

REST API yanıtları standart HTTP GET istekleri olduğu için Varnish veya Cloudflare gibi CDN sistemlerinde URI bazlı kolayca önbelleklenir. GraphQL istekleri ise varsayılan olarak HTTP POST methodu kullandığı için uç noktada (Edge) önbellekleme yapmak özel konfigürasyon gerektirir. Bu sorunu aşmak için WPGraphQL Smart Cache eklentisi aracılığıyla GET isteklerine destek vermek veya GraphQL persist queries (kalıcı sorgular) tekniğini uygulamak gerekir.

Sonuç

GraphQL nedir sorusuna yanıt aradığımız bu rehberde; mimarinin sunduğu esnekliği, REST API karşısındaki avantajlarını ve WPGraphQL eklentisi ile WordPress'i modern bir Headless altyapıya nasıl dönüştüreceğimizi inceledik. GraphQL, istemci taraflı veri ihtiyaçlarını tam isabetle karşılayarak gereksiz ağ trafiğini engeller ve yazılım geliştirme süreçlerine yüksek bir standart kazandırır.

Sonraki adım olarak, lokal WordPress kurulumunuza WPGraphQL eklentisini dahil edebilir, Next.js veya React projenize verileri bağlayarak ilk Headless WordPress denemenizi hayata geçirebilirsiniz.