GraphQL ve REST: API Tasarımında Hangisi, Hangi Durumda?

Ortak zemin: istemci ile sunucu arasındaki sözleşme

REST, Roy Fielding'in doktora tezinde tanımladığı bir mimari stildir. İstemci ile sunucunun ayrılması, her isteğin sunucunun ihtiyaç duyduğu tüm bilgiyi taşıması (durumsuzluk), yanıtların önbelleğe alınabilir olarak işaretlenmesi, tek tip arayüz ve katmanlı sistem bu stilin temel kısıtlarıdır. Uygulamada REST API'ler kaynakları URL'lerle adlandırır ve HTTP metotlarıyla (GET, POST, PUT, DELETE) bu kaynaklar üzerinde işlem yapar.

GraphQL ise bir API sorgu dili ve çalışma zamanıdır. Sunucu, güçlü bir tip sistemiyle tanımlanan bir şema sunar; istemci bu şemaya göre tam olarak ihtiyaç duyduğu alanları isteyen sorgular yazar. Okuma için sorgular (query), değişiklik için mutasyonlar (mutation), gerçek zamanlı veri için abonelikler (subscription) kullanılır.

İkisi de aynı problemi çözer: istemcinin, örneğin bir mobil uygulamanın ya da web arayüzünün, sunucudaki veriye ve işlemlere tanımlı bir sözleşmeyle erişmesi. İkisi de genellikle HTTP üzerinden JSON taşır. Fark, sözleşmenin kaynak ve URL üzerinden mi, yoksa tek bir tipli şema üzerinden mi kurulduğundadır.

Veri çekme biçimi nasıl farklılaşır?

REST'te her kaynağın kendi uç noktası vardır. Bir sipariş detay ekranı için örneğin önce sipariş, sonra müşteri, sonra sipariş kalemleri ayrı uç noktalardan çekilebilir. Bu, ekran başına birden fazla istek yapılması (eksik veri çekme) ya da uç noktanın ekranın ihtiyacından fazla alan döndürmesi (fazla veri çekme) sonucunu doğurabilir. Ekip buna, ekrana özel uç noktalar ya da alan seçme parametreleri ekleyerek yanıt verir.

GraphQL'de, graphql.org'un HTTP üzerinden sunum rehberine göre tüm istekler tek bir uç noktaya, genellikle /graphql adresine gönderilir. İstemci tek bir sorguyla siparişi, müşterinin adını ve kalemlerin yalnız gereken alanlarını iç içe ister; yanıt sorgunun şekliyle birebir döner. Yeni bir ekran yeni bir uç nokta gerektirmez, yalnız yeni bir sorgu gerektirir.

Bu esnekliğin sunucu tarafında bedeli vardır. Her alan bir çözümleyici (resolver) fonksiyonla doldurulur; iç içe listelerde her öğe için ayrı veritabanı sorgusu atılması, yaygın olarak N+1 sorunu diye anılan performans tuzağına yol açar. Bunu önlemek için istekleri toplu yükleyen yardımcılar ve sorgu karmaşıklığı sınırları kullanılır.

Temel farklar: ölçüt ölçüt

• Sözleşme: GraphQL / tek bir tipli şema; istemci şemadan istediği alanları seçer. REST / kaynak başına uç noktalar; yanıt yapısını sunucu belirler, sözleşme genellikle OpenAPI ile belgelenir.
• Uç nokta: GraphQL / tek uç nokta. REST / kaynak ve işlem başına çok sayıda URL.
• Veri miktarı: GraphQL / ekranın ihtiyacı kadar alan, tek istekte iç içe veri. REST / sabit yanıt yapısı; fazla ya da eksik veri çekme riski.
• HTTP önbellekleme: GraphQL / graphql.org'a göre URL benzeri evrensel bir tanımlayıcı olmadığı için nesneler için benzersiz kimlik alanı tanımlamak iyi uygulamadır; önbellekleme çoğunlukla istemci kütüphanesinde yapılır. REST / URL kaynağın benzersiz tanımlayıcısıdır, HTTP ve CDN önbelleği doğal olarak çalışır.
• Sürümleme: GraphQL / şemaya alan eklenir, eski alan kullanımdan kaldırıldı diye işaretlenir; genellikle sürümsüz evrim. REST / yol ya da başlıkta sürüm numarası yaygındır.
• Hata yönetimi: GraphQL / yanıtta veri varsa kısmi başarı durumunda bile başarılı bir HTTP durum kodu dönebilir, hatalar yanıt gövdesindeki errors alanında taşınır. REST / HTTP durum kodları hatanın türünü doğrudan anlatır.
• Gerçek zamanlı veri: GraphQL / abonelikler şemanın parçasıdır. REST / ayrıca WebSocket ya da sunucu olayları gibi bir kanal kurulur.
• Güvenlik ve sınırlama: GraphQL / sorgu derinliği, karmaşıklık ve alan düzeyinde yetki kontrolü gerekir. REST / uç nokta bazında yetki ve hız sınırlaması daha basittir.

REST hangi durumda doğru seçimdir?

• API dış dünyaya, iş ortaklarına ya da geniş bir geliştirici kitlesine açılacaksa; REST'in HTTP kavramlarıyla birebir örtüşmesi entegrasyonu kolaylaştırır
• Yanıtların CDN ya da ara katman önbelleğinden sunulması performans için kritikse
• Kaynaklar basit ve ekranlar kaynaklarla birebir örtüşüyorsa, örneğin bir dosya yükleme ya da ödeme bildirimi servisi
• Webhook, dosya indirme, akış gibi HTTP'ye özgü davranışlar ağırlıktaysa
• Ekip ve kullanılan araçlar OpenAPI tabanlı belgeleme ve test zincirine dayanıyorsa

Örneğin bir kargo firmasının, e-ticaret sitelerinin gönderi oluşturması ve takip numarası sorgulaması için açtığı API'de kaynaklar nettir, entegratörler farklı dillerde çalışır ve önbellekleme önemlidir; bu senaryo REST'in doğal alanıdır.

GraphQL hangi durumda öne çıkar?

• Aynı veriyi farklı ihtiyaçlarla tüketen çok sayıda istemci varsa: web, mobil, akıllı saat, iş ortağı paneli
• Ekranlar birden fazla kaynaktan iç içe veri gerektiriyorsa ve mobil ağda istek sayısını azaltmak önemliyse
• Ön yüz ekipleri sık değişen ekranlar için arka uç ekibini beklemeden veri ihtiyacını tanımlamak istiyorsa
• Birden fazla arka uç servisini istemciye tek bir şema altında sunmak gerekiyorsa; bu, federasyon ya da şema birleştirme yaklaşımlarıyla yapılır

Örneğin bir haber uygulamasının ana sayfası, makaleleri, yazar bilgisini, yorum sayısını ve kullanıcının kaydettiği içerikleri tek ekranda gösterir. Web sürümü daha fazla alan, mobil sürüm daha az alan ister. GraphQL ile iki istemci aynı şemadan kendi ihtiyacına göre sorgu yazar, sunucuda ekrana özel uç nokta çoğalmaz.

Birlikte kullanım ve sık yapılan hatalar

İki yaklaşım aynı sistemde sık sık birlikte yaşar. Yaygın bir kurguda iç servisler REST ile konuşur, istemciye bakan katmanda ise bu servisleri birleştiren bir GraphQL ağ geçidi bulunur. Dış entegrasyonlar için REST, kendi uygulamalarının ön yüzü için GraphQL sunan kurumlar da vardır.

Sık yapılan hatalar: • GraphQL şemasını veritabanı tablolarının birebir kopyası olarak tasarlamak; şema istemcinin alan dilini yansıtmalıdır • Sorgu derinliği ve karmaşıklık sınırı koymamak; kötü niyetli ya da hatalı bir sorgu sunucuyu kilitleyebilir • Toplu yükleme kullanmadan çözümleyici yazmak ve N+1 sorununu canlıda fark etmek • REST'te her şeyi POST ile yapmak, durum kodlarını anlamsız kullanmak ve kaynak yerine eylem adlı URL'ler kurmak • Teknolojiyi değiştirmeyi, kötü tasarlanmış bir API'nin çözümü sanmak; iki yaklaşımda da asıl belirleyici iyi bir alan modeli ve tutarlı sözleşmedir

Mindset programlarında bu konular

GraphQL ile API Geliştirme programı GraphQL temelleri ve REST karşılaştırmasıyla başlar; şema tasarımı, çözümleyici geliştirme, kimlik doğrulama ve yetkilendirme, performans ve güvenlik, abonelikler ile üretim ve federasyon başlıklarını işler.

REST tarafındaki REST API pratikleri programı REST temelleri ve kısıtları, kaynak modelleme ve URI tasarımı, HTTP metotları ve durum kodlarının doğru kullanımı, sayfalama, filtreleme, önbellekleme ile API testi ve belgelemeyi kapsar. API'yi bir ürün olarak yönetmek isteyenler için API Tasarımı ve Yönetimi programı sürümleme, API güvenliği, API ağ geçidi ve OpenAPI ile belgeleme modüllerini içerir.