REST API vs GraphQL: Hangisini Seçmeli?

Yeni bir projeye başlarken sık karşılaşılan kararlardan biri şudur: REST vs GraphQL — API katmanını hangi yaklaşımla kuracaksın? İkisi de istemci ile sunucu arasında veri taşımanın olgun, kanıtlanmış yollarıdır; ama farklı problemleri farklı biçimde çözerler. Bu yazıda iki yaklaşımın temel mantığını, güçlü ve zayıf yanlarını, over/under-fetching ve önbellekleme gibi pratik konuları, son olarak da hangi durumda hangisini seçmen gerektiğini anlatıyorum.

İki yaklaşımın temel mantığı

REST, kaynakları (resource) URL'lerle modeller. Her kaynağın bir adresi vardır ve HTTP fiilleriyle (GET, POST, PUT, DELETE) üzerinde işlem yaparsın. Tipik olarak /users/42 bir kullanıcıyı, /users/42/posts o kullanıcının gönderilerini döner. Sunucu hangi alanları döneceğine kendisi karar verir.

GraphQL ise tek bir endpoint (genelde /graphql) üzerinden çalışan bir sorgu dilidir. İstemci tam olarak hangi alanları istediğini bir sorguyla belirtir, sunucu da yalnızca o alanları döner. Yani veri şekline karar veren taraf sunucu değil, istemcidir.

Aynı veriyi iki yaklaşımla karşılaştıralım. REST'te bir kullanıcıyı çekmek:

GET /users/42

{
  "id": 42,
  "name": "Aslain",
  "email": "hello@aslain.dev",
  "createdAt": "2026-01-10"
}

GraphQL'de aynı kullanıcının yalnızca ad ve e-postasını istemek:

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

Yanıt da istenen şekle birebir uyar:

{
  "data": {
    "user": { "name": "Aslain", "email": "hello@aslain.dev" }
  }
}

Over-fetching ve under-fetching

GraphQL'in en çok öne çıkarılan avantajı bu iki kavramla ilgilidir. Over-fetching, ihtiyacından fazla veri almandır: REST'te /users/42 sana adı, e-postayı, kayıt tarihini ve belki on alan daha döner; ama sen yalnızca adı göstereceksen geri kalanı boşa taşınmıştır.

Under-fetching ise tek istekle yeterli veriyi alamamandır. Bir kullanıcıyı ve son beş gönderisini göstermek için REST'te önce /users/42, sonra /users/42/posts diye iki istek atman gerekir — buna N+1 istek problemi denir. GraphQL'de bunların hepsini tek sorguda iç içe isteyebilirsin:

query {
  user(id: 42) {
    name
    posts(last: 5) { title publishedAt }
  }
}

Bu, özellikle mobil uygulamalarda ve düşük bant genişliğinde gerçek bir kazançtır. Ama dikkat: REST tarafında da bu sorunlar çözülebilir. ?fields=name,email gibi alan seçici parametreler over-fetching'i, ?include=posts gibi gömme (embedding) parametreleri ise under-fetching'i büyük ölçüde giderir. Yani GraphQL'in çözdüğü şeyler REST'te imkânsız değildir; sadece tasarım disiplini ister.

Önbellekleme: REST'in güçlü yanı

İşte burada terazi REST'e doğru kayar. REST, HTTP'nin doğal önbellekleme mekanizmalarıyla mükemmel uyum içindedir. Her kaynağın benzersiz bir URL'i olduğu için tarayıcılar, CDN'ler ve ters proxy'ler (Nginx, Varnish, Cloudflare) GET yanıtlarını Cache-Control, ETag ve Last-Modified başlıklarına göre kolayca önbelleğe alır.

GraphQL'de ise neredeyse her şey tek bir POST /graphql isteğidir ve gövdesi her seferinde farklıdır. HTTP düzeyinde önbellekleme bu yüzden zordur; önbelleği genelde istemci tarafına (Apollo Client, urql, Relay gibi kütüphanelerin normalize edilmiş önbelleğine) ya da sunucu tarafında alan bazlı çözümlere (örneğin persisted queries) taşırsın. Bu güçlü ama daha fazla kurulum ister.

Şema, tipler ve geliştirici deneyimi

GraphQL güçlü bir tip sistemine sahiptir. Şema (schema) bir sözleşmedir: hangi alanların var olduğunu, tiplerini ve ilişkilerini açıkça tanımlar. Bu sayede:

• Otomatik dokümantasyon: GraphiQL veya Apollo Studio gibi araçlar şemadan canlı, gezilebilir bir dokümantasyon üretir.
• Tip güvenliği: TypeScript kod üreticileriyle istemci tarafında uçtan uca tipler elde edersin.
• Tek kaynaktan çok ekran: Web, mobil ve farklı istemciler aynı şemadan ihtiyaç duyduklarını çeker; arka uç ekibi her ekran için yeni endpoint açmak zorunda kalmaz.

REST tarafında benzer güvenceyi OpenAPI (eski adıyla Swagger) ile elde edebilirsin. OpenAPI şeması da dokümantasyon ve istemci kodu üretimi sağlar; ancak GraphQL'de tip sistemi dilin doğasında olduğu için bu disiplin daha kendiliğinden gelir.

Karmaşıklık ve dikkat edilmesi gerekenler

GraphQL bedava gelmez. Esnekliğin bedeli, sunucu tarafında bazı sorunları kendin çözmek zorunda olmandır:

• N+1 sorgu problemi: İç içe alanlar veritabanına çok sayıda ayrı sorgu atabilir. Bunu çözmek için DataLoader gibi toplu yükleme (batching) araçları kullanmak gerekir.
• Sorgu maliyeti: İstemci çok derin veya çok geniş bir sorgu atarak sunucuyu zorlayabilir. Sorgu derinliği sınırlama ve maliyet analizi (query cost analysis) şarttır.
• Önbellekleme ve hata yönetimi: Yukarıda anlatıldığı gibi HTTP önbelleği zayıftır; ayrıca GraphQL hatalı durumlarda bile 200 OK döner ve hatayı gövdedeki errors alanında taşır, bu da izlemeyi değiştirir.

REST ise basitliğiyle kazanır. HTTP durum kodları (404, 201, 401) doğal olarak anlamlıdır, araç ekosistemi devasadır ve neredeyse her geliştirici REST'i zaten bilir. Küçük ve orta projelerde bu sadelik çoğu zaman en doğru tercihtir.

Hangisini ne zaman seçmeli?

Kestirme bir kural yok ama şu kriterler kararı kolaylaştırır:

• REST'i seç: Kaynaklar net ve sade ise, HTTP önbellekleme ve CDN senin için kritikse, ekip REST'e aşinaysa, ya da herkese açık basit bir API yayınlıyorsan.
• GraphQL'i seç: Çok sayıda farklı istemcin (web + mobil) varsa ve her biri farklı veri şekli istiyorsa, iç içe ilişkiler karmaşıksa, ya da arka uç ile ön uç ekipleri hızlı ve bağımsız ilerlemek istiyorsa.

Unutma: bu bir "ya o ya bu" savaşı değildir. Birçok ekip ikisini birlikte kullanır — örneğin GraphQL'i istemci odaklı veri toplama için, REST'i ise dosya yükleme, webhook ve üçüncü taraf entegrasyonları için. Önemli olan ideolojiye değil, projenin gerçek ihtiyacına bakmaktır.

Sık Sorulan Sorular

GraphQL, REST'in yerini alacak mı?

Hayır. GraphQL bazı senaryolarda REST'ten daha rahat bir geliştirici deneyimi sunsa da, REST'in basitliği ve HTTP önbelleklemeyle uyumu hâlâ çok değerlidir. İkisi yıllardır yan yana yaşıyor ve yaşamaya devam edecek; doğru araç tamamen kullanım senaryona bağlıdır.

GraphQL daha mı hızlıdır?

Tek başına "daha hızlı" demek yanıltıcıdır. GraphQL ağ üzerinde gereksiz veriyi azaltarak ve birden çok isteği tek sorguda birleştirerek istemci tarafındaki algılanan hızı artırabilir. Ama sunucu tarafında N+1 sorguları düzgün yönetilmezse REST'ten daha yavaş bile olabilir. Hız, mimarine ve optimizasyonuna bağlıdır.

Mevcut REST API'mi GraphQL'e taşımalı mıyım?

Çalışan bir REST API'yi yalnızca moda olduğu için baştan yazmak nadiren mantıklıdır. Gerçek bir over/under-fetching acısı çekiyorsan ya da istemci çeşitliliğin arttıysa, GraphQL'i mevcut REST'in üzerine bir katman olarak eklemek (gateway yaklaşımı) çoğu zaman daha akıllıca bir yoldur.

API mimarini doğru kurmak ister misin? REST veya GraphQL, Laravel ve Node.js tarafında ölçeklenebilir bir API tasarımı için yardıma ihtiyacın varsa benimle iletişime geç — projene en uygun yaklaşımı birlikte seçelim.