GraphQL Baslangic Rehberi: Esnek API Sorgulari

GraphQL Nedir?

GraphQL, Facebook tarafindan 2012 yilinda gelistirilen ve 2015 yilinda acik kaynak olarak yayinlanan bir API sorgu dilidir. REST API'lerden farkli olarak, istemcinin tam olarak hangi verilere ihtiyac duydigunu belirtmesine olanak tanir. Sunucu, istenen veriden ne fazlasini ne de eksigini dondurur. Bu yaklasim, over-fetching (fazla veri cekmek) ve under-fetching (eksik veri cekmek) sorunlarini kokten ortadan kaldirir.

2026 yilinda GraphQL, GitHub, Shopify, Twitter, Airbnb ve daha pek cok buyuk platform tarafindan uretimde kullanilmaktadir. Ozellikle karmasik veri iliskileri olan projeler, mobil uygulamalar ve mikro servis mimarileri icin guclu bir secenektir. Bu rehberde, GraphQL'in temel kavramlarindan uygulamali kullanima, Apollo Client entegrasyonundan REST ile karsilastirmasina kadar her seyi ele aliyoruz.

REST vs. GraphQL

GraphQL'i anlamak icin once REST API'lerin sinirliklarini bilmek faydalidir.

GraphQL Temel Kavramlari

Schema (Sema)

GraphQL API'sinin kalbidir. Schema, API'nin sunabilecegi tum veri tiplerini, iliskilerini ve islemleri tanimlar. Guclu tip sistemi (type system) sayesinde hem istemci hem sunucu tarafinda veri yapisinin dogru oldugu garanti edilir. Schema, API'nizin sozlesmesidir ve otomatik dokumantasyon olusturulmasini saglar.

Type (Tip)

Veri yapilarini tanimlar. GraphQL'de her sey bir tiptir. Skaler tipler (String, Int, Float, Boolean, ID), nesne tipleri (Object), enum tipleri, arayuz (Interface) ve birlestirme (Union) tipleri mevcuttur. Her alanin bir tipi vardir ve nullable olup olmadigi belirtilir.

Query (Sorgu)

Veri okuma islemleri icin kullanilir. REST'teki GET isteklerine karsilik gelir. Istemci, istedigialanlari belirterek sorgu gonderir ve sunucu yalnizca istenen verileri dondurur. Ic ice sorgular ile iliskili verileri tek bir istekte alabilirsiniz.

Mutation (Mutasyon)

Veri yazma, guncelleme ve silme islemleri icin kullanilir. REST'teki POST, PUT, PATCH, DELETE isteklerine karsilik gelir. Bir mutation calistirildiktan sonra, guncellenmis veriyi ayni istekte geri alabilirsiniz.

Subscription (Abonelik)

Gercek zamanli veri guncellemeleri icin kullanilir. WebSocket uzerinden calisir ve sunucuda bir degisiklik oldugunda istemciye otomatik olarak bildirim gonderilir. Canli sohbet, bildirimler, canli veri akislari gibi senaryolar icin idealdir.

Resolver'lar: Verinin Kaynagi

Resolver, schema'daki her alanin verisinin nereden ve nasil getirilecegini tanimlayan fonksiyonlardir. Bir query veya mutation calistirdiginda, GraphQL sunucusu ilgili resolver fonksiyonlarini cagirir.

Resolver Yapisi

Her resolver dort parametre alir:

• parent: Ust resolver'dan gelen sonuc. Ic ice sorgularda veri zincirleme icin kullanilir.
• args: Istemcinin gonderdigi argumanlar. Filtreleme, sayfalama, ID gibi parametreler buradan alinir.
• context: Tum resolver'lar arasinda paylasilan bilgiler. Veritabani baglantisi, kimlik dogrulama bilgileri, veri yukleyiciler (dataloaders) burada bulunur.
• info: Sorgu hakkinda meta bilgiler. Hangi alanlarin istendigi, sorgu agaci gibi detaylar icerir.

Veri Kaynaklari

Resolver'lar herhangi bir veri kaynagindan veri cekebilir: SQL/NoSQL veritabanlari, REST API'leri, diger GraphQL API'leri, dosya sistemi, cache servisleri veya hesaplanmis degerler. Bu esneklik, GraphQL'i mevcut altyapilar uzerine bir katman olarak eklemeyi kolaylastirir.

Apollo Client: Frontend Entegrasyonu

Apollo Client, React (ve diger framework'ler) ile GraphQL API'leri arasindaki iletisimi yoneten en populer istemci kutuphanesidir. Veri getirme, onbellekleme, durum yonetimi ve hata isklemeyi tek bir catida birlestirir.

Apollo Client Ozellikleri

• Normalizasyonlu Cache: Gelen veriler otomatik olarak normalize edilir ve onbelleklenir. Ayni veriyi talep eden farkli bilesenler, ag istegi yapmadan cache'ten beslenir.
• useQuery Hook: React bilesenlerinde veri cekmenin en yaygin yolu. Loading, error ve data durumlarini otomatik yonetir.
• useMutation Hook: Veri yazma islemleri icin. Mutasyon sonrasi cache otomatik guncellenir.
• Optimistic Updates: Sunucu yaniti beklenmeden UI'yi aninda guncelleyerek daha hizli bir kullanici deneyimi saglar. Hata durumunda otomatik geri alma (rollback) yapilir.
• Pagination: Offset ve cursor tabanli sayfalama icin yerlesik yardimci fonksiyonlar sunar.
• DevTools: Apollo Client DevTools tarayici eklentisi ile cache durumunu, sorgulari ve performansi inceleyebilirsiniz.

GraphQL Sunucu Secenekleri

GraphQL API olusturmak icin birkac populer sunucu framework'u mevcuttur:

• Apollo Server: En yaygin kullanilan GraphQL sunucusu. Express, Koa, Fastify ve serverless ortamlarla uyumlu. Guclu eklenti sistemi ve kapsamli dokumantasyon.
• GraphQL Yoga: The Guild tarafindan gelistirilen, modern ve performansli bir GraphQL sunucusu. Envelop eklenti sistemi ile genisletilebilir.
• Hasura: PostgreSQL veritabanini otomatik olarak GraphQL API'ye donusturen bir platform. Sifir kodla CRUD islemleri, gercek zamanli abonelikler ve yetkilendirme kurallar.
• Pothos (eski adi GraphQL Nexus): TypeScript-first schema builder. Tip guvenli schema tanimlama ile gelistirme deneyimini iyilestirir.

GraphQL En Iyi Uygulamalari

Schema Tasarimi

• Istemci odakli dusunun: Schema'yi veritabani yapisiniza degil, istemcinin ihtiyaclarina gore tasarlayin.
• Tutarli adlandirma: camelCase alan adlari, PascalCase tip adlari, UPPER_CASE enum degerleri kullanin.
• Null degerleri bilinclice yonetin: Her alanin nullable olup olmamasi gerektigini dikkatle degerlendirin.
• Sayfalama tasarimi: Buyuk listeler icin Relay Connection spesifikasyonunu (edges, nodes, pageInfo) degerlendirin.

Performans

• DataLoader kullanin: N+1 sorgu problemini onlemek icin DataLoader ile toplu veri getirme (batching) yapin.
• Sorgu derinligi sinirlayin: Kotu niyetli veya hatali ic ice sorgularin sunucuyu cokertmesini onlemek icin derinlik siniri koyun.
• Sorgu karmasikligi analizi: Her alanin bir maliyeti olmali ve toplam sorgu maliyeti sinirlanmalidir.
• Persisted queries: Uretim ortaminda yalnizca onceden tanimlanmis sorgularin calistirilmasina izin vererek guvenlik ve performansi artirin.

GraphQL Ne Zaman Kullanilmali?

GraphQL her proje icin dogru secim olmayabilir. Iste GraphQL'in parlaidigi ve yetersiz kaldigi senaryolar:

GraphQL Idealdir

• Karmasik ve ic ice iliskili veri yapilari olan projeler.
• Birden fazla istemcinin (web, mobil, IoT) ayni API'yi farkli veri ihtiyaclariyla kullandigi durumlar.
• Hizli iterasyon gerektiren projeler — frontend degisiklikleri backend degisikligi gerektirmez.
• Mikro servis mimarilerinde birden fazla servisi tek bir API katmaninda birlestirmek istediginizde.
• Gercek zamanli veri guncellemeleri gereken uygulamalar (subscription ile).

REST Daha Uygun Olabilir

• Basit CRUD islemlerinden olusan, karmasik iliskileri olmayan API'ler.
• Dosya yukleme agirlikli uygulamalar.
• Tarayici onbelleklemesinin kritik oldugu senaryolar (GraphQL POST kullandigi icin HTTP cache zorlaşir).
• Ekibin GraphQL deneyiminin sinirli oldugu ve ogrenme suresinin butceye uymadigi projeler.

GraphQL Baslangic Kontrol Listesi

1. Projenizin veri yapisini ve iliiskilerini haritalandirin.
2. Schema'nizi istemci ihtiyaclarina gore tasarlayin.
3. GraphQL sunucu framework'unu secin (Apollo Server, GraphQL Yoga vb.).
4. Tip tanimlarini ve resolver'lari olusturun.
5. DataLoader ile N+1 sorgu problemini onleyin.
6. Kimlik dogrulama ve yetkilendirme katmanini ekleyin.
7. Apollo Client veya urql ile frontend entegrasyonunu yapilandirin.
8. Sorgu derinligi ve karmasikligi sinirlarini belirleyin.
9. Hata iskleme stratejinizi tanimlayin.
10. GraphQL Playground veya Apollo Studio ile API'nizi test edin.

Sonuc:GraphQL, dogru senaryolarda muhtesem bir gelistirici deneyimi ve performans sunlar. Guclu tip sistemi, esnek sorgu yapisi ve zengin ekosistemi ile modern API gelistirmenin guclu bir aracıdır. Megis olarak, projelerimizde veri ihtiyaclariniz dogrultusunda GraphQL veya REST'i stratejik olarak degerlendiriyor ve en uygun cozumu uyguluyoruz.