GraphQL API’yi host etmek: REST’ten farklar ve pratik plan

GraphQL API’leri barındırırken (host ederken) “aynı altyapı, farklı bir endpoint” gibi düşünmek çoğu zaman yanıltır. REST’te her istek belirli bir kaynak üzerinde hareket ederken, GraphQL’de istek tek bir endpoint’e gider ve istemci istediği alanları sorgu olarak gönderir. Bu nedenle performans, cache, güvenlik ve izleme metrikleri REST’ten ayrışır. Bu rehberde GraphQL’i Türkiye’deki kullanıcı hedefiyle barındırmanın operasyonel tarafını; REST ile doğrudan farkları ve pratik bir kurulum/işletim planı üzerinden anlatıyorum.

GraphQL vs REST: Mimari farklar neleri değiştirir?

Tek endpoint + alan bazlı istek

REST’te genelde /users/123 gibi kaynak odaklı URL’ler vardır. GraphQL’de ise çoğu senaryoda tek bir endpoint kullanılır: örneğin /graphql.

Bu, şu sonuçları doğurur: - Sunucu tarafı parser/validator maliyeti artar: Her istek bir sorgu (query) üretir; bu sorgu doğrulanır. - Kontrol mekanizmaları farklılaşır: REST’te URL ve method bazlı rate limit yapmak daha kolaydır. GraphQL’de aynı endpoint’e farklı sorgular gelebilir. - Yanıt boyutu istemci tarafından alan alan seçildiği için dalgalanır.

Over-fetching / under-fetching

REST’te sabit response şemaları “gereksiz alan” (over-fetching) üretebilir. GraphQL bu problemi, istemcinin seçtiği alanlarla çözer; ancak bunun bedeli “aşırı karmaşık query” (çok derin veya çok geniş sorgu) şeklinde performansa yansıyabilir.

Bu nedenle GraphQL host ederken teknik kararların odağı şu sorular olur: - Sorgular ne kadar maliyetli olabilir? - İzin verilen sorgu derinliği ve karmaşıklığı nasıl kısıtlanır? - Önbellek (cache) nerede ve ne kadar çalışır?

Versiyonlama stratejisi

REST’te API versiyonlama genellikle URL üzerinden yapılır (ör. /v1/...). GraphQL’de şema (schema) üzerinden yönetim daha yaygındır.

Host açısından etkisi: - Şema değişiklikleri için geri uyumluluk izleme ister. - CI/CD pipeline içinde şema testleri (schema diff, contract test) daha kritik hale gelir.

GraphQL performansı: REST’ten farklı 4 kritik konu

1) Sorgu maliyeti (query complexity) ve depth limit

GraphQL’in en büyük operasyonel riski, istemcinin “işletim maliyeti yüksek” bir query göndermesi ve bu yüzden CPU/IO tüketiminin yükselmesidir. Bu sorun REST’te URL bazlı daha kolay kontrol edilebilirken GraphQL’de query içeriğine bakmak gerekir.

Pratikte yapılacaklar: - Depth limit: Örneğin maksimum 8-15 seviye gibi bir sınır belirlenir. - Complexity limit: Alanların ağırlığı (cost) hesaplanır; örn. toplam maliyet 200-500 üstü ise reddedilir. - Timeout: Query yürütme süresi için sunucu tarafında kesin süre sınırı konur.

Net hedef: “Tek istek tek işlemciyi kilitlesin” senaryosunu engellemek.

2) Veri katmanı: N+1 query tuzağı

GraphQL’de resolver’lar alan alan çalışır. Bu yüzden yanlış tasarımda N+1 problem büyür: örneğin 1 kullanıcı listesindeki her kullanıcı için ayrı DB sorgusu yapmak.

Çözüm: - Dataloader (veya benzeri batching) kullanarak istekleri gruplayın. - Resolver’ları “tek query ile topluca veri çekmeye” göre tasarlayın. - Mümkünse join/aggregate ile veri çekimini azaltın.

3) Cache: REST’te HTTP cache daha öngörülebilir

REST’te HTTP cache (ETag, Cache-Control) daha kolay uygulanır. GraphQL’te ise istemci alanları seçtiği için cache varyant sayısı artar.

Uygulanabilecek net yaklaşım: - Eğer yanıtlar büyük ölçüde aynı alanlarla geliyor ise persisted queries (persist edilmiş sorgular) ile cache anahtarını stabilize edin. - Uygun olduğunda response caching uygulayın (ör. belirli sorgu + değişmeyen parametrelerle). - Çoğu uygulamada “tam otomatik her şeyi cache’le” yaklaşımı değil, hedefli cache en sürdürülebilir olandır.

4) Rate limit: Endpoint bazlı değil, sorgu bazlı

REST’te /graphql tek endpoint olduğu için kaba rate limit zorlaşır. En doğrusu istemciyi şu kırılımlarla korumaktır: - IP bazlı limit - Kullanıcı/Api-Key bazlı limit - Query complexity (veya depth) ile orantılı limit

Net öneri: “Ağır query”leri daha sıkı kısıtlayın. Hafif sorgular için daha geniş pencere tanımlayın.

Güvenlik ve operasyon: GraphQL host ederken net kontrol listesi

[1] Yetkilendirme (authorization) katmanı

GraphQL’de yetki kontrolünü resolver seviyesinde yapmak şarttır; çünkü tek endpoint olsa da hangi alanların döneceği sorguyla belirlenir.

Yapılacaklar: - Kimlik doğrulama (auth) sonrası user context’i resolver’lara iletin. - Alan bazlı yetkilendirme kurallarını şemaya (schema directives) veya resolver middleware’larına bağlayın. - Introspection gibi keşif fonksiyonlarını üretimde sınırlayın.

[2] Dosya boyutu ve sorgu sınırları

Host tarafında şu eşikler net belirlenmeli: - Request body boyutu limiti - Maksimum query string uzunluğu - Maksimum response alan sayısı (uygulanabiliyorsa)

[3] Logging ve izleme: “hangi query yavaş?” sorusunun cevabı

REST’te route bazlı metrik almak daha kolay olur. GraphQL’de loglarda şunlar olmalı: - Kullanılan operasyon adı (operationName) veya hash - Complexity/scan sonucu - Resolver süresi toplamı (span) - DB sorgu sayısı ve toplam süre

Bu sayede “Türkiye’deki kullanıcılar neden 2-3 saniye görüyor?” gibi sorulara somut yanıt üretirsiniz.

Altyapı seçimi: VDS/VPS/dedicated ve performans beklentisi

GraphQL’i host etmek için gereken altyapı, uygulamanın çözümleme hızı, veri kaynağı (DB) ve dış servis bağımlılıklarına göre değişir. Yine de REST’ten farklı olarak CPU ve memory dalgalanması daha görünür olabilir çünkü query maliyeti değişkendir.

Uygulama profiline göre pratik eşleştirme

Aşağıdaki tablo, karar vermenizi hızlandırmak için “tipik” eşleştirmeler içerir:

Not: Burada “tek doğru spec” yok; kritik olan GraphQL’in query maliyetini ölçüp kısıtlarken aynı zamanda DB tarafını N+1’den arındırmaktır.

Depolama, DB ve cache stratejisi: GraphQL’de asıl fark DB’de çıkar

GraphQL host ederken performansın büyük kısmı genellikle uygulama sunucusundan ziyade veri katmanında şekillenir. Özellikle şunlar etkiler: - N+1 sorgular - İndeks (index) eksikliği - Çok sayıda küçük sorgunun IO maliyeti - Cache misses

DB tarafında net öneriler

• Sık kullanılan filtre/arama kolonlarında index oluşturun.
• İlişkili tablolarla veri çekerken toplam sorgu sayısını azaltın.
• read yoğunluğu varsa read-replica (master-slave) mimarisini planlayın.

Cache tarafında net öneriler

• Şema ve resolver tasarımına göre “en çok dönen” sorguları tespit edin.
• Bu sorgular için response caching (veya materyalize edilmiş veri) uygulayın.
• Cache geçersizleştirmeyi “sürekli TTL ile” değil, veri güncelleme olaylarıyla daha deterministik yapın.

REST’ten GraphQL’e geçerken en sık yapılan 7 hata

1. Query complexity/ depth limit koymamak
2. Resolver’larda N+1’i fark etmeden veri çekmek
3. Loglarda operation adı veya sorgu maliyeti olmaması
4. Her yanıtı cache’lemeye çalışıp cache çeşitliliğiyle sistemi karmaşıklaştırmak
5. Authorization’ı tek yerde çözümleyip alan bazlı kontrolü atlamak
6. Timeout ve circuit breaker benzeri korumaları ihmal etmek
7. Şema değişikliğini test etmeden üretime almak

Kurulum ve işletim planı: “ilk 14 gün” yol haritası

1-3. gün: Şemayı ve sınırları tanımlayın

• Field/operation isimlendirmesi standardını kurun.
• Query complexity ve depth limit belirleyin.
• Query timeout değerini tanımlayın.

4-7. gün: Veri katmanı ve N+1 temizliği

• En çok kullanılan sorguları seçin.
• Dataloader/batching ile resolver’ları optimize edin.
• DB tarafında gerekirse index ekleyin.

8-10. gün: Rate limit ve yetkilendirme

• IP + API key bazlı rate limit kurun.
• Auth sonrası user context’le alan bazlı izinleri doğrulayın.

11-14. gün: İzleme, log standardı ve cache pilotu

• Tracing/span ile resolver sürelerini görünür kılın.
• “cache’lenmeye en uygun sorguları” belirleyip küçük bir pilot yapın.

Sonuç: GraphQL host ederken REST’te olmayan 3 kararı şimdi alın

GraphQL API host etmek; endpoint farkından çok query maliyeti, resolver performansı ve alan bazlı güvenlik konularını öne çıkarır. Kararınızı hızlandırmak için şu 3 adımı aksiyon planı olarak net alın: - İlk gün query complexity + depth limit ve timeout tanımlayın. - İkinci adım olarak N+1 sorunlarını resolver bazında ölçüp temizleyin. - Son olarak log/izleme standardını kurup “hangi sorgu yavaşladı?” sorusunu dakikalar içinde yanıtlayacak hale getirin.

Bunları kurduğunuzda GraphQL ile REST arasındaki farklar yönetilebilir bir mühendislik konusu olur; performans ve güvenlik hedeflerinize daha öngörülebilir şekilde ulaşırsınız.