GraphQL Nedir? REST’ten Geçiş için Net Rehber

Giriş

GraphQL, “mobilde fazla veri geliyor”, “tek ekranda 5 API çağrısı yapıyorum”, “frontend her değişiklikte backend’e bağımlı kalıyor” gibi sorunların en pratik çözümlerinden biri. REST ile büyüyen projelerde over-fetching (gereğinden fazla veri) ve under-fetching (eksik veri) problemleri çoğu zaman performans, geliştirme hızı ve ekip bağımsızlığına direkt etki eder.

Bu yazıda GraphQL nedir sorusunu netleştireceğiz; hangi senaryolarda REST’e göre avantaj sağladığını, nasıl çalıştığını ve küçük bir örnekle nasıl ayağa kaldırabileceğinizi adım adım göreceksiniz. Ayrıca pagination, cache, güvenlik ve üretim ortamında dikkat edilmesi gereken noktaları da ekleyeceğim.

GraphQL Nedir? (Kısa ve Net)

GraphQL, istemcinin (frontend/mobil) ihtiyaç duyduğu veriyi tam olarak tarif ederek sunucudan almasını sağlayan bir API sorgulama dili ve çalışma zamanıdır. Genellikle tek bir endpoint üzerinden çalışır ve veri şekli client tarafından belirlenir.

Bunu neden yapmalıyım?

• Tek ekranda farklı kaynaklardan gelen verileri tek istekle toplayabilirsiniz.
• Frontend ekibi “şu alanı da ekler misin?” döngüsünü azaltır; alanlar şemada varsa sorguya ekler.
• API sözleşmesi şema ile netleşir; self-documented bir yapı oluşur.

REST vs GraphQL: Ne Zaman Hangisi?

Aşağıdaki tablo karar vermeyi kolaylaştırır:

Gerçek hayat örneği: E-ticaret ürün detay sayfasında “ürün + fiyat + stok + yorumlar + öneriler” aynı anda gösteriliyorsa REST’te genelde 4–6 istek görürsünüz. GraphQL ile tek sorguda hepsini çekmek mümkün olur (doğru tasarlanırsa).

GraphQL’in Temel Yapı Taşları

1) Schema (Şema)

GraphQL’in kalbi şemadır. Veri tipleri ve alanlar burada tanımlanır.

2) Query / Mutation / Subscription

• Query: Veri okuma
• Mutation: Veri değiştirme (create/update/delete)
• Subscription: Gerçek zamanlı (WebSocket) akış

3) Resolver

Bir alanın verisini nereden bulacağını söyleyen fonksiyon. DB, REST servis, cache vb. olabilir.

Bunu neden yapmalıyım? Şema + resolver yaklaşımı, API’nizi “endpoint koleksiyonu” değil, “domain modeli” gibi düşünmenizi sağlar.

20 Dakikada Mini GraphQL API (Node.js + Apollo)

Aşağıdaki örnek, kavramları hızlıca oturtmak için ideal.

Adım 1: Projeyi başlatın

mkdir graphql-demo && cd graphql-demo
npm init -y
npm i @apollo/server graphql

Not: Basitlik için Node’un http modülüyle çalıştıracağız.

Adım 2: Basit bir server ve schema yazın

index.js

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';

const typeDefs = `#graphql
  type User {
    id: ID!
    name: String!
    role: String!
  }

  type Query {
    me: User!
    user(id: ID!): User
    users: [User!]!
  }
`;

const users = [
  { id: '1', name: 'Ayşe', role: 'founder' },
  { id: '2', name: 'Mehmet', role: 'developer' },
];

const resolvers = {
  Query: {
    me: () => users[0],
    user: (_, { id }) => users.find(u => u.id === id),
    users: () => users,
  },
};

const server = new ApolloServer({ typeDefs, resolvers });

const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
});

console.log(`GraphQL ready at: ${url}`);

Çalıştırın:

node index.js

Adım 3: İlk Query’nizi deneyin

Tarayıcıdan http://localhost:4000 açın ve şu sorguyu çalıştırın:

query {
  users {
    id
    name
  }
}

Önemli nokta: role alanını istemediğiniz için gelmez. İşte GraphQL’in en büyük “tıklayan” faydası burada.

GraphQL’te Performans: N+1 Problemi ve Çözümü

GraphQL esneklik verir ama yanlış resolver tasarımı N+1 query problemine yol açabilir.

Senaryo:

• orders listesi çekiliyor
• her order’ın user alanı resolver’da ayrı DB çağrısı yapıyor
• 50 order => 1 + 50 sorgu

Çözüm yaklaşımı

• Batching ve caching (DataLoader benzeri) kullanın
• Resolver’larda mümkünse “tek seferde çek” mantığı kurun

Bunu neden yapmalıyım? GraphQL’te darboğaz çoğu zaman query dili değil, resolver’ların data erişim stratejisidir.

Pagination: Offset Yerine Cursor Kullanın

GraphQL’te en yaygın ihtiyaçlardan biri pagination.

Cursor pagination neden iyi?

• Büyük tablolarda offset yavaşlar
• Sıralama değişimlerinde sayfa atlaması/tekrarı azalır

Örnek (konsept):

query {
  products(first: 20, after: "cursor123") {
    edges {
      node { id name price }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Güvenlik: GraphQL’te En Kritik 4 Önlem

GraphQL tek endpoint olduğu için güvenlik yaklaşımı REST’ten farklılaşır.

1. Query depth limit (çok derin sorgulara limit)
2. Complexity limit (çok pahalı sorguları engelle)
3. Rate limiting (IP/Token bazlı)
4. Persisted queries (özellikle mobilde: sadece izin verilen query hash’leri)

Bunu neden yapmalıyım? GraphQL’de saldırı yüzeyi genellikle “endpoint sayısı” değil, “sorgu esnekliği”dir.

REST’ten GraphQL’e Geçiş Stratejisi (Risk Almadan)

Tam rewrite çoğu ekip için riskli. Bunun yerine kademeli ilerleyin:

1) BFF (Backend for Frontend) ile başlayın

GraphQL katmanı, mevcut REST servislerini çağırıp tek noktadan sunabilir.

2) En çok acıtan ekranı seçin

Örn: dashboard / product detail / admin panel listesi.

3) Şemayı domain odaklı kurgulayın

Endpoint isimleri yerine iş kavramları: User, Order, Product.

4) İzleme ekleyin

• En yavaş query’ler
• En sık kullanılan alanlar
• Hatalı resolver oranları

Sık Sorulan Sorular (FAQ)

1) GraphQL nedir, REST’in yerine mi geçer?

GraphQL REST’in yerine geçmek zorunda değil. Birçok ekip hibrit kullanır: bazı yerler REST, bazı yerler GraphQL.

2) GraphQL tek endpoint ise cache nasıl yapılır?

HTTP seviyesinde cache zorlaşabilir. Genelde uygulama içi cache, persisted queries ve iyi resolver stratejileriyle çözülür.

3) GraphQL performansı her zaman daha mı iyi?

Hayır. Doğru tasarlanmazsa N+1 gibi problemlerle daha kötü olabilir. Performans, resolver ve veri erişimiyle kazanılır.

4) GraphQL öğrenmesi zor mu?

Temel query/mutation ve şema mantığı hızlı öğrenilir. Asıl ustalık pagination, güvenlik ve resolver tasarımında gelir.

Sonuç

Bu rehberde GraphQL nedir sorusunu; şema, resolver mantığı, küçük bir Node.js örneği, pagination, performans ve güvenlik perspektifiyle ele aldık. GraphQL özellikle çok ekranlı, hızlı değişen ürünlerde frontend-backend bağımlılığını azaltıp geliştirme hızını artırabilir.

Bir sonraki adım: Kendi projenizde en çok istek atan (veya en çok veri taşıyan) 1 ekranı seçin, küçük bir GraphQL katmanı ile deneyin. Denediğiniz senaryoyu yorumlarda paylaşın; birlikte en iyi şema tasarımını tartışalım.