GraphQL API Geliştirme: Schema Design, DataLoader ve N+1 Çözümü

GraphQL vs REST: Ne Zaman Hangi Teknoloji Kullanmalı?

API mimarisi seçimi, projenin başarısını doğrudan etkiler. GraphQL ve REST arasındaki seçim, proje gereksinimlerinize göre yapılmalıdır.

REST (Representational State Transfer), HTTP fiillerini kullanan, kaynak odaklı bir yaklaşımdır. Basit ve stateless tasarım, REST'i birçok proje için anlaşılır kılar. Ancak karmaşık veri ilişkileri yönetirken aşırı veri transferi (over-fetching) veya birden fazla istek gereksinimine (under-fetching) yol açabilir.

GraphQL ise bir sorgu dilidir ve istemci tam olarak hangi verileri istediğini belirtir. Strongly typed schema sayesinde self-documenting API sağlar ve mobile uygulamalar için veri transfer maliyetini azaltır. Bunun karşılığında öğrenme eğrisi daha dik ve caching mekanizmaları REST'ten farklıdır.

Kriter	REST	GraphQL
Basitlik	Yüksek	Düşük
Real-time	WebSocket gerekli	Subscription desteği
Caching	HTTP cache	Kompleks
Mobile Optimizasyonu	Birden fazla istek	Tek istek
Over-fetching Sorunu	Var	Yok
Öğrenme Eğrisi	Kolay	Zor

GraphQL, karmaşık veri ilişkileri ve mobile uygulamalar için idealdir. Basit CRUD operasyonları için REST yeterli olabilir.

Schema-First vs Code-First Yaklaşımlar

GraphQL schema tasarımında iki temel paradigma vardır. Schema-first yaklaşımda, GraphQL Schema Definition Language (SDL) kullanarak schema önce yazılır, ardından resolver'lar implementasyon bulur. Bu yöntem client ve server arasındaki sözleşmeyi net bir şekilde tanımlar. Tasarım aşamasında review yapılabilir ve language-agnostic olduğu için farklı teknolojilerdeki ekiplerin işbirliğini kolaylaştırır.

Code-first yaklaşım ise TypeScript gibi programlama dilinde type definitions yazılır ve GraphQL schema otomatik olarak üretilir. Bu yöntem TypeScript type safety ve IDE otomatik tamamlanma desteği sağlar. NestJS gibi framework'ler bu yaklaşımı teşvik eder. Dezavantajı schema değişiklikleri kod değişiklikleri gerektirmesidir.

Smart Maple, TypeScript ve NestJS kullanan code-first yaklaşımını tercih eder. Type safety ve IDE desteği, enterprise uygulamalar için kritiktir ve geliştiricilerin hataları daha erken yakalamasını sağlar.

GraphQL Type System ve Tasarım Desenleri

GraphQL'in gücü, strongly typed schema'sından gelir. Scalar türler (String, Int, Float, Boolean, ID, Date) temel veri tiplerini tanımlar. Enum türleri ise sabit değer seçeneklerini (örneğin ACTIVE, PENDING, ARCHIVED) tanımlamak için kullanılır. Interface ve Union türleri ise karmaşık veri ilişkilerini model etmeye yardımcı olur.

Resolver'lar, GraphQL query'lerini veritabanı sorgularına dönüştürür. Verimli resolver yazma, API performansı için kritiktir. Her resolver, istemcinin talep ettiği veriyi sağlamalı ve unnecessary veritabanı çağrılarından kaçınmalıdır.

N+1 Problemi ve DataLoader Çözümü

GraphQL'de sık karşılaşılan bir sorun, N+1 query problemidir. Örneğin, 100 danışmanı listelemek ve her birinin tüm randevularını göstermek istenirse, 1 sorgu (100 danışmanı getir) artı 100 sorgu (her danışman için randevuları getir) = 101 sorgu çalıştırılır.

DataLoader bu problemi batch loading ile çözer. Istemci tarafından istenen tüm danışmanların IDs'lerini toplar ve veritabanına tek bir sorgu gönderir: "Bu 100 danışmanın tüm randevularını getir". Sonra sonuçları doğru sırayla eşleştirir. Bu teknik veritabanı yükünü önemli ölçüde azaltır ve API yanıt süresini hızlandırır.

Pagination: Relay Cursor Standardı

Modern GraphQL uygulamalarında Relay connection pattern'ı tercih edilir. Cursor-based pagination, offset-based pagination'dan daha güvenilirdir çünkü veri silinmesi durumunda tutarsız sonuçlar vermez.

Relay pattern'ında, her sayfa bir startCursor ve endCursor ile tanımlanır. İstemci, "şu cursor'dan sonra 10 satır getir" diyerek sayfalanır. Bu yöntem, veri değişse bile istikrarlı sonuçlar garanti eder.

Özellik	Offset-based	Cursor-based
Stabilite	Veri silinirse hata	Stabil
Kullanım	Basit	Biraz karışık
Yüksek offset	Yavaş	Hızlı

Subscriptions: Real-Time Veri İletişimi

GraphQL Subscriptions, WebSocket üzerinden real-time veri iletişimi sağlar. Kullanıcılar, yeni randevu oluşturulduğunda veya danışmanın statüsü değiştiğinde anında bilgilendirilir. Bu, canlı güncellemeler, bildirimler ve işbirliğine izin verir.

Subscriptions, server tarafından olayları publish ettiği ve client'ların bu olaylara subscribe olduğu bir model kullanır. Örneğin, bir randevu oluşturulduğunda sunucu bu olayı tüm dinleyicilere yayınlar.

Microservices Ortamında: Federation

Büyük sistemlerde birden fazla GraphQL API'yi birleştirmek gerekir. Apollo Federation, modern bir yaklaşımdır. Farklı microservices'ler kendi GraphQL subgraph'larını yönetir ve Apollo Gateway tüm subgraph'ları bir unified graph'ta birleştirir.

Federation, her service'in bağımsız kalmasını sağlarken, client'lar tüm API'yi tek bir endpoint üzerinden kullanabilir. Type extension ve @key directive'leri kullanarak type'lar farklı service'ler arasında ilişkilendirilir.

Özellik	Schema Stitching	Apollo Federation
Kurulum	Basit	Daha Kompleks
Subgraph Otonomi	Düşük	Yüksek
Type Extension	Manual	Deklaratif
Performance	Orta	Yüksek
Community Support	Eski	Güncel

Apollo Federation, büyük microservices ekosistemler için tercih edilir.

Security: Sorgu Karmaşıklığı Yönetimi

GraphQL, DoS saldırılarına açıktır. Çok derin veya kompleks sorgular sunucuyu çökertebilir. Bu nedenle query complexity limiting uygulanmalıdır. Server, gelen sorguyu analiz eder, karmaşıklık puanını hesaplar ve limit aşarsa reddet.

Rate limiting de kritiktir. Aynı IP'den aşırı sayıda istek yapılmasını kontrol etmelisiniz. Persisted queries tekniği ise önceden onaylanmış sorgular listesini kullanarak, random sorgulardan kaçınmayı sağlar.

Authentication, context nesnesinde tutulan token veya user bilgileri aracılığıyla uygulanır. Resolver'lar, context'i kontrol ederek yetkilendirme kurallarını enforce eder.

Gerçek Dünya Örneği: Sağlık Danışmanı Planlama

Smart Maple, Ankara'da sağlık danışmanlarının randevu yönetimi için GraphQL API geliştirmiştir. Sistem, danışmanlar, hastalar, randevular ve slot'ları yönetir.

Şema tasarımında, Consultant type'ı name, email, expertise, rating ve totalAppointments alanları içerir. ConsultantSlot type'ı startTime, endTime, status ve capacity alanları barındırır. Appointment type'ı patientName, appointmentTime, durationMinutes ve status alanlarından oluşur.

Resolver'lar, available consultant'ları sorgulamak, müsait slot'ları listelemek, yeni randevu oluşturmak ve iptal etmek gibi işlemleri yönetir. DataLoader, her randevuya ait danışmanı getirirken N+1 sorgu problemini çözer.

Performance İyileştirme Teknikleri

GraphQL'de performance, veri yönetimi ve query optimizasyonu ile sağlanır.

Select Argümanlarıyla Veri Seçimi: Resolver, GraphQL info nesnesini analiz ederek istemcinin hangi alanları istediğini belirler. Sadece gerekli veritabanı sütunları veya ilişkileri yükler. Böylece unnecessary veri transferini önler.

Query Batching: Istemci-side batching, birden fazla query'i toplar ve belirlenen aralıklarda toplu gönderir. Ağ gecikmesini azaltır ve server yükünü balanslar.

Caching Stratejileri: Apollo Client, InMemoryCache kullanarak query sonuçlarını local'de tutar. Aynı query tekrar çalıştırılırsa, cache'den alınır. Type policies sayesinde, belirli query'ler için özel cache kuralları tanımlanabilir.

Hata Yönetimi ve Validasyon

Validation kuralları schema seviyesinde tanımlanmalıdır. İsim boş olamaz, email formatı doğru olmalı, şifre minimum 8 karakter olmalıdır gibi kurallar input type'ında belirtilir.

Hata yöneştirme, GraphQL error extension'larını kullanarak yapılır. Her hata bir code (ör. INVALID_INPUT, NOT_FOUND) ve isteğe bağlı ek alanları (ör. invalidFields) içerir. Böylece client'lar hatanın nedenini anlar ve uygun şekilde yanıt verir.

Özet ve Best Practices

GraphQL API geliştirmesinde başarı için:

1. Schema tasarımına dikkat edin - İyi tasarlanan schema, gelecekteki değişiklikleri kolaylaştırır
2. N+1 problemi çözün - DataLoader kullanımı performans için kritiktir
3. Security'yi ciddiye alın - Complexity limiting, rate limiting ve authentication kullanın
4. Real-time gereksinimler için Subscriptions kullanın
5. Microservices için Apollo Federation tercih edin
6. Validation ve error handling tutarlı yapın

Smart Maple, GraphQL API geliştirmede uzmanlaşmıştır. Ankara'da kurulu ekibimiz, Node.js, NestJS, Apollo Server ve PostgreSQL kullanarak enterprise-grade uygulamalar geliştiriyor. Aylık 3.500 TL developer maliyetiyle, büyük ölçekli API projelerini teslim ediyoruz.

GraphQL teknolojisini master etmek, modern API tasarımında önemli bir adımdır. Sorularınız için smart-maple.com adresinden iletişime geçebilirsiniz.

İlgili Rehberler

• RESTful API Tasarım Rehberi
• API Performans Optimizasyonu