GraphQL vs REST: Modern API Tasarım Rehberi

API Tasarımında Yeni Dönem

Modern yazılım geliştirme dünyasında API'ler, uygulamaların birbirleriyle iletişim kurmasının temel yapı taşlarıdır. Yıllardır REST (Representational State Transfer) bu alanda fiilen standart olarak kabul edilirken, 2015 yılında Facebook tarafından açık kaynak olarak sunulan GraphQL, oyunun kurallarını değiştirmeye başladı. Peki hangisi sizin projeniz için doğru seçim? Bu rehberde her iki yaklaşımı derinlemesine karşılaştıracağız.

REST Nedir?

REST, Roy Fielding tarafından 2000 yılında doktora tezinde tanımlanan bir mimari stildir. HTTP protokolü üzerine kuruludur ve kaynakları (resources) URL'ler aracılığıyla temsil eder. Her kaynak için standart HTTP metotları (GET, POST, PUT, DELETE) kullanılarak CRUD işlemleri gerçekleştirilir.

REST'in Temel Prensipleri

• Stateless (Durumsuz): Her istek, sunucunun ihtiyaç duyduğu tüm bilgiyi içerir.
• Uniform Interface (Tekdüze Arayüz): Kaynaklar tutarlı bir şekilde URI'lar ile temsil edilir.
• Cacheable (Önbelleğe Alınabilir): Yanıtlar açıkça önbelleğe alınabilir veya alınamaz olarak işaretlenebilir.
• Client-Server Ayrımı: İstemci ve sunucu birbirinden bağımsız olarak geliştirilebilir.
• Katmanlı Sistem: İstemci, doğrudan sunucuya mı yoksa bir aracıya mı bağlı olduğunu bilmek zorunda değildir.

Tipik Bir REST API Örneği

GET    /api/users          → Tüm kullanıcıları listele
GET    /api/users/42       → 42 ID'li kullanıcıyı getir
POST   /api/users          → Yeni kullanıcı oluştur
PUT    /api/users/42       → 42 ID'li kullanıcıyı güncelle
DELETE /api/users/42       → 42 ID'li kullanıcıyı sil
GET    /api/users/42/posts → 42 ID'li kullanıcının yazılarını getir

GraphQL Nedir?

GraphQL, hem bir sorgu dili hem de bir çalışma zamanıdır (runtime). İstemcinin tam olarak hangi verilere ihtiyaç duyduğunu belirtmesine olanak tanır. Tek bir endpoint üzerinden çalışır ve istemci, yanıtın şeklini kendisi tanımlar.

GraphQL'in Temel Kavramları

• Schema: API'nin sunduğu tüm veri tiplerini ve ilişkilerini tanımlayan sözleşme.
• Query: Veri okuma işlemleri için kullanılan sorgu türü.
• Mutation: Veri yazma, güncelleme ve silme işlemleri için kullanılan sorgu türü.
• Subscription: Gerçek zamanlı veri güncellemeleri için kullanılan mekanizma.
• Resolver: Her alan için verinin nereden ve nasıl getirileceğini belirleyen fonksiyonlar.

GraphQL Schema ve Sorgu Örneği

# Schema tanımı
type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  createdAt: String!
}

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

type Mutation {
  createUser(name: String!, email: String!): User!
}

# İstemci sorgusu
query {
  user(id: "42") {
    name
    email
    posts {
      title
      createdAt
    }
  }
}

// Yanıt
{
  "data": {
    "user": {
      "name": "Fatih Arslan",
      "email": "fatih@example.com",
      "posts": [
        {
          "title": "GraphQL'e Giriş",
          "createdAt": "2026-03-15"
        },
        {
          "title": "API Tasarım Desenleri",
          "createdAt": "2026-03-20"
        }
      ]
    }
  }
}

Over-fetching ve Under-fetching Problemi

REST API'lerin en bilinen sorunlarından biri over-fetching ve under-fetching problemleridir. GraphQL bu sorunu kökten çözmek için tasarlanmıştır.

Over-fetching (Aşırı Veri Çekme)

Bir kullanıcının sadece adını göstermek istediğiniz bir ekran düşünün. REST ile GET /api/users/42 çağrısı yaptığınızda sunucu, kullanıcıya ait tüm alanları döner: ad, e-posta, adres, telefon, profil fotoğrafı URL'i ve daha fazlası. Siz sadece adı kullanacak olsanız bile tüm bu veri ağ üzerinden taşınır.

GraphQL'de ise sadece ihtiyacınız olanı istersiniz:

query {
  user(id: "42") {
    name
  }
}

Under-fetching (Yetersiz Veri Çekme)

Bir kullanıcı profil sayfasında kullanıcı bilgileri, yazıları ve takipçi listesini göstermek istiyorsanız, REST ile en az üç ayrı istek yapmanız gerekir:

GET /api/users/42
GET /api/users/42/posts
GET /api/users/42/followers

GraphQL'de tüm bu verileri tek bir sorguda alabilirsiniz:

query {
  user(id: "42") {
    name
    email
    posts {
      title
      content
    }
    followers {
      name
      avatarUrl
    }
  }
}

Performans Karşılaştırması

Ağ Performansı

GraphQL, tek bir HTTP isteğiyle birden fazla kaynağa erişim sağladığı için ağ gecikme süresini (latency) önemli ölçüde azaltabilir. Özellikle mobil uygulamalarda ve düşük bant genişliğine sahip ortamlarda bu fark belirgin hale gelir.

Önbellekleme (Caching)

REST bu konuda doğal bir avantaja sahiptir. Her kaynağın kendine ait bir URL'i olduğundan, HTTP önbellekleme mekanizmaları (CDN, tarayıcı önbelleği, proxy cache) doğrudan kullanılabilir. GraphQL'de ise tüm istekler genellikle aynı endpoint'e POST olarak gönderildiğinden, HTTP düzeyinde önbellekleme doğrudan mümkün değildir. Bu sorunu çözmek için Apollo Client, Relay veya urql gibi istemci kütüphaneleri normalize edilmiş önbellek stratejileri sunar.

Sunucu Tarafı Performans

GraphQL'in esnekliği bir bedelle gelir. İstemcinin karmaşık ve derinlemesine iç içe sorgular göndermesi, sunucuda beklenmedik yüklere neden olabilir. Bu durumu kontrol altına almak için birkaç strateji uygulanmalıdır:

• Query Depth Limiting: Sorguların maksimum derinliğini sınırlayın.
• Query Complexity Analysis: Her alanın bir maliyeti olsun ve toplam maliyet bir eşiği geçemesin.
• DataLoader Pattern: N+1 sorgu problemini çözmek için istekleri toplu hale getirin (batching).
• Persisted Queries: Üretimde yalnızca önceden onaylanmış sorguların çalışmasına izin verin.

Node.js ile DataLoader Kullanımı

const DataLoader = require('dataloader');

// N+1 sorgu problemini çözen DataLoader
const userLoader = new DataLoader(async (userIds) => {
  const users = await db.users.findByIds(userIds);
  // ID sırasına göre düzenle
  return userIds.map(id => users.find(u => u.id === id));
});

const resolvers = {
  Post: {
    author: (post) => userLoader.load(post.authorId)
  }
};

Geliştirici Deneyimi (DX)

REST'in Güçlü Yanları

• Basitlik: HTTP'yi bilen herkes REST API kullanabilir. Curl, Postman veya herhangi bir HTTP istemcisi yeterlidir.
• Olgunluk: Yıllardır kullanılan araçlar, kütüphaneler ve en iyi pratikler mevcuttur.
• OpenAPI/Swagger: Güçlü dokümantasyon ve kod üretme araçları bulunur.
• Standart HTTP Durum Kodları: 200, 404, 500 gibi kodlar anlam taşır ve araçlar tarafından anlaşılır.

GraphQL'in Güçlü Yanları

• Güçlü Tip Sistemi: Schema, API'nin canlı dokümantasyonudur. Her alan, tipi ve ilişkisi açıkça tanımlıdır.
• Introspection: API kendi kendini tanımlayabilir, bu da araçların otomatik tamamlama ve doğrulama yapmasına olanak tanır.
• GraphiQL ve Apollo Studio: Etkileşimli sorgu editörleri, geliştirme sürecini hızlandırır.
• Kod Üretimi: Schema'dan otomatik olarak tip güvenli istemci kodu üretilebilir.

# GraphQL Code Generator ile tip güvenli istemci
# codegen.yml
schema: "http://localhost:4000/graphql"
documents: "src/**/*.graphql"
generates:
  src/generated/graphql.ts:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo

Versiyon Yönetimi

REST'te Versiyonlama

REST API'lerde kırılıcı değişiklikler yapıldığında genellikle yeni bir versiyon oluşturulur:

/api/v1/users
/api/v2/users

Bu yaklaşım, birden fazla versiyonun paralel olarak bakımını gerektirdiğinden uzun vadede yük oluşturur.

GraphQL'de Evrim

GraphQL, versiyonlama yerine schema evrimini tercih eder. Yeni alanlar eklemek mevcut istemcileri bozmaz. Kaldırılması gereken alanlar @deprecated direktifi ile işaretlenir:

type User {
  id: ID!
  name: String!
  fullName: String!
  username: String @deprecated(reason: "fullName alanını kullanın")
}

Güvenlik Konuları

Her iki yaklaşımda da dikkat edilmesi gereken güvenlik konuları farklılık gösterir:

REST Güvenliği

• Rate limiting endpoint bazında kolayca uygulanabilir.
• Her endpoint için ayrı yetkilendirme kuralları tanımlanabilir.
• HTTP düzeyindeki güvenlik araçları (WAF, API Gateway) doğrudan çalışır.

GraphQL Güvenliği

• Tek endpoint olduğundan rate limiting daha karmaşıktır; sorgu karmaşıklığına göre sınırlama yapılmalıdır.
• Introspection üretim ortamında kapatılmalıdır.
• Alan düzeyinde yetkilendirme uygulanmalıdır (resolver bazlı).
• Sorgu derinliği ve karmaşıklığı mutlaka sınırlandırılmalıdır.

Ne Zaman Hangisini Seçmeli?

REST'i Tercih Edin Eğer:

1. Basit CRUD operasyonları yapıyorsanız ve veri ilişkileri karmaşık değilse.
2. HTTP önbellekleme mekanizmalarından maksimum fayda sağlamak istiyorsanız.
3. Takımınız REST konusunda deneyimli ama GraphQL'e yeni ise.
4. Dosya yükleme gibi işlemler API'nizin önemli bir parçasıysa.
5. Herkese açık (public) bir API sunuyorsanız ve geniş bir geliştirici kitlesine ulaşmak istiyorsanız.
6. Microservice'ler arası iç iletişim için basit ve hızlı bir çözüm arıyorsanız.

GraphQL'i Tercih Edin Eğer:

1. İstemciler farklı platformlarda (web, mobil, IoT) çalışıyor ve farklı veri ihtiyaçları varsa.
2. Veriler arasında karmaşık ilişkiler mevcutsa ve bunlar sık sık iç içe sorgulanıyorsa.
3. Ön yüz ekibi, arka yüz ekibinden bağımsız hızlı iterasyon yapmak istiyorsa.
4. Birden fazla veri kaynağını tek bir API katmanında birleştirmek istiyorsanız (API Gateway / Federation).
5. Gerçek zamanlı veri güncellemeleri (subscriptions) projenizin doğal bir parçasıysa.
6. Tip güvenliği ve otomatik dokümantasyon önceliğinizse.

Hibrit Yaklaşım: İkisini Birlikte Kullanmak

Gerçek dünyada birçok büyük ölçekli sistem her iki teknolojiyi birlikte kullanır. Örneğin, dahili microservice'ler REST veya gRPC ile iletişim kurarken, istemciye dönük katmanda bir GraphQL gateway kullanılabilir. Bu yaklaşım Backend for Frontend (BFF) deseniyle uyumludur ve her iki dünyanın da avantajlarından yararlanmanızı sağlar.

┌──────────────┐
│   İstemciler  │  (Web, Mobil, IoT)
└──────┬───────┘
       │  GraphQL
┌──────▼───────┐
│ GraphQL      │
│ Gateway      │  (Apollo Federation / Schema Stitching)
└──┬────┬────┬─┘
   │    │    │    REST / gRPC
┌──▼┐ ┌▼──┐ ┌▼──┐
│Srv│ │Srv│ │Srv│  (Microservice'ler)
│ A │ │ B │ │ C │
└───┘ └───┘ └───┘

Sonuç

GraphQL ve REST birbirinin alternatifi olmaktan çok, farklı problem alanlarına optimize edilmiş araçlardır. REST, basitliği, olgunluğu ve geniş ekosistemiyle birçok senaryo için hâlâ mükemmel bir seçimdir. GraphQL ise esnekliği, güçlü tip sistemi ve istemci odaklı yaklaşımıyla karmaşık ve çok platformlu projelerde öne çıkar.

Doğru seçimi yapmak için projenizin gereksinimlerini, takımınızın deneyimini ve uygulamanızın ölçek hedeflerini dikkate alın. Unutmayın: en iyi API, kullanıcılarınızın ihtiyaçlarını en verimli şekilde karşılayan API'dir.