GraphQL Nedir? Modern API Tasarımına Giriş Rehberi

Bir mobil ekranı doldurmak için üç ayrı REST endpoint'ine istek atıp, dönen verinin büyük kısmını hiç kullanmadan atmak zorunda kaldıysanız, GraphQL tam bu sorunu çözmek için tasarlandı. Facebook'un geliştirip açık kaynak hâline getirdiği bu sorgulama dili, istemcinin sunucudan yalnızca ihtiyaç duyduğu alanları istemesine izin verir. Bu rehberde GraphQL'in REST'ten farkını, şema ve tip sistemini, sorgu-mutasyon-çözücü mantığını ve pratikte nelere dikkat etmeniz gerektiğini ele alıyoruz.

GraphQL Nedir ve Hangi Sorunu Çözer

GraphQL, istemcinin sunucudan hangi alanları istediğini tek tek belirleyebildiği bir API sorgulama dilidir. REST API'lerinde her endpoint sabit bir veri yapısı döndürür. İstemci bazen ihtiyacından fazla veri alır (over-fetching), bazen aynı ekranı doldurmak için birkaç endpoint'e art arda istek atmak zorunda kalır (under-fetching). GraphQL, tek istekte tam olarak istenen veriyi döndürerek bu iki sorunu birden ortadan kaldırır.

Bir örnek üzerinden bakalım. Bir kullanıcı profilinde yalnızca isim ve e-posta göstermek istiyorsanız, sorgu şöyle yazılır:

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

Sunucu tam olarak bu iki alanı döndürür, ne fazlasını ne eksiğini. REST'te aynı işlem için genelde kullanıcının tüm bilgilerini (adres, telefon, kayıt tarihi dahil) çekip, gerekmeyen kısmı istemci tarafında ayıklamanız gerekir.

Bu fark mobil uygulamalarda daha belirgin hissedilir. Sınırlı bir veri bağlantısında gereksiz alanları indirmek hem yükleme süresini uzatır hem kullanıcının veri paketini tüketir. GraphQL'in alan bazlı seçimi bu israfı doğrudan kaldırdığı için mobil öncelikli projelerde sık tercih edilir.

REST ile Karşılaştırma

REST'te her kaynağın kendi endpoint'i vardır: /users/42, /users/42/orders, /users/42/reviews gibi. Karmaşık bir ekran, bu endpoint'lerin birkaçına art arda istek atmayı gerektirebilir. GraphQL'de genelde tek bir endpoint bulunur ve istemci, ihtiyaç duyduğu tüm ilişkili veriyi tek sorguda toplar.

Bu, GraphQL'in her durumda REST'in yerine geçmesi gerektiği anlamına gelmez. Basit, kaynak odaklı bir API için REST'in sadeliği hâlâ avantajlıdır; HTTP önbellekleme mekanizmaları REST ile doğal biçimde çalışır. GraphQL ise karmaşık, iç içe geçmiş veri ihtiyaçları olan ve birden fazla istemci türüne (web, mobil, TV uygulaması) hizmet eden projelerde asıl gücünü gösterir.

Bazı ekipler iki yaklaşımı bir arada kullanır: dosya yükleme gibi basit işlemleri REST üzerinden, karmaşık veri okuma işlemlerini GraphQL üzerinden yürütür. Bu hibrit kullanım, her aracı güçlü olduğu alanda çalıştırmayı sağlar.

Şemadan sorgulara kadar tüm temel kavramlar GraphQL'in resmi dokümantasyonu'nda örneklerle anlatılıyor.

Şema ve Tip Sistemi

Her GraphQL API'si bir şemayla tanımlanır. Şema, hangi verilerin sorgulanabileceğini ve bu verilerin tiplerini net biçimde ortaya koyar. Örnek bir tip tanımı şöyle görünür:

type User {
  id: ID!
  name: String!
  email: String!
  orders: [Order]
}

Bu tanım, bir User nesnesinin hangi alanlara sahip olduğunu ve bu alanların tiplerini açıkça gösterir. Var olmayan bir alanı isteyen geçersiz bir sorgu, çalışma zamanında değil doğrulama aşamasında yakalanır. Bu, hataları erken tespit etmenin pratik bir yoludur.

Şemanın kendini belgelemesi GraphQL'in en kullanışlı özelliklerinden biridir. Introspection adı verilen bu yetenek sayesinde geliştirici araçları API'nin sunduğu tüm alanları otomatik keşfedip listeleyebilir. Ayrı bir API dokümanına bakmak yerine doğrudan şemayı sorgulayarak nelerin mevcut olduğunu görebilirsiniz. Bu, yeni bir ekip üyesinin projeye alışma süresini de kısaltır.

Sorgular, Mutasyonlar ve Çözücüler

GraphQL'de üç temel işlem türü bulunur. Sorgular (query) veri okumak için kullanılır, mutasyonlar (mutation) ise veri oluşturma, güncelleme ve silme işlemlerini kapsar. Bir mutasyon örneği şöyle yazılır:

mutation {
  updateUser(id: "42", name: "Ayşe Kaya") {
    id
    name
  }
}

Çözücüler (resolver), bu işlemlerin arkasındaki asıl mekanizmadır. Her alan için, o alanın verisinin nereden ve nasıl getirileceğini tanımlayan bir fonksiyon çalışır. Sorgu geldiğinde sunucu, ilgili çözücüleri sırayla çağırarak veriyi veritabanından, başka bir API'den ya da farklı bir mikro servisten toplar.

Bu mimari GraphQL'i özellikle dağıtık sistemlerde değerli kılar. Tek bir sorgu, arka planda birden fazla veri kaynağını birleştirebilir. İstemci bu karmaşıklığı görmez, yalnızca tek ve tutarlı bir API ile konuşur. Bu soyutlama, mikro servis mimarilerinde GraphQL'in tercih edilme nedenlerinden biridir.

GraphQL'in Sağladığı Somut Avantajlar

Veri getirme verimliliği en belirgin avantajdır: istemci yalnızca ihtiyacı olan alanları alır. Bu, özellikle mobil cihazlarda ve yavaş bağlantılarda ölçülebilir bir performans kazancı sağlar. Farklı istemcilere (web, iOS, Android) aynı esnek API üzerinden hizmet vermek, her platform için ayrı endpoint tasarlama zorunluluğunu kaldırır.

Geliştirme hızı da bu avantajlardan biridir. Ön uç ekibi, arka uç ekibinden yeni bir endpoint beklemeden, mevcut şemadan ihtiyaç duyduğu veri kombinasyonunu doğrudan sorgulayabilir. Bu bağımsızlık, özellikle büyük ekiplerde teslim sürelerini kısaltır.

Versiyon yönetimi de GraphQL'de farklı işler. REST API'lerinde yeni bir alan eklemek genelde /v2/users gibi yeni bir sürüm gerektirir. GraphQL'de ise şemaya yeni alanlar eklemek eski sorguları bozmaz. Bu geriye dönük uyumluluk, API'yi zamanla genişletmeyi daha az riskli hâle getirir.

Dikkat Edilmesi Gereken Riskler

GraphQL'in esnekliği aynı zamanda bir risk kaynağıdır. İstemci, çok derin iç içe geçmiş bir sorgu göndererek sunucuya beklenmedik bir yük bindirebilir. Bu tür sorgular kötü niyetle de kullanılabilir. Sorgu derinliğini ve karmaşıklığını sınırlamak, GraphQL API'lerini güvenli tutmanın temel önlemlerinden biridir.

Önbellekleme, REST'e göre daha fazla planlama gerektirir. REST'in sabit URL'leri HTTP önbelleklemeyi doğal biçimde destekler. GraphQL'in tek endpoint'i ve değişken sorgu yapısı bu basitliği ortadan kaldırır. Bunun yerine istemci tarafı kütüphaneleri (Apollo Client, Relay gibi) kendi önbellekleme mekanizmalarını kullanır.

Aşağıdaki tablo iki yaklaşımı kısaca karşılaştırıyor:

GraphQL'i Ne Zaman Seçmeli

Karmaşık, birbirine bağlı veri ihtiyaçları olan ve birden fazla istemci türüne hizmet eden projeler, GraphQL'den en çok yararlanan senaryolardır. Basit, birkaç kaynaklı bir CRUD API için REST'in düşük öğrenme eğrisi ve HTTP önbellekleme kolaylığı hâlâ cazip bir seçenektir.

Ekibin GraphQL'e ne kadar aşina olduğu da karar sürecinde göz ardı edilmemelidir. Şema tasarımı, çözücü mimarisi ve önbellekleme stratejisi öğrenmek zaman alır. Bu yatırımın karşılığını verecek bir proje ölçeği olup olmadığını baştan değerlendirmek, ileride teknik borç birikmesini önler.

Zengin bir araç ekosistemi bu öğrenme sürecini kolaylaştırır. Etkileşimli sorgu gezginleri (GraphiQL, Apollo Studio gibi) şemayı görsel olarak keşfetmenizi, sorguları test etmenizi ve hataları anında görmenizi sağlar. Bu araçlar, yeni bir API'yi ayrı bir dokümana bakmadan öğrenmeyi mümkün kılar.

Yazan Celil Uyanikoglu

25 yıldır bilgi işlem piyasasında farklı dallarda uzmanlaşan bir Bilgisayar Mühendisi