REST API, GraphQL ve gRPC Farkı Nedir

Dağıtık yazılım sistemlerinde, mobil uygulamalarda, tek sayfa web arayüzlerinde (SPA) ve bulut yerel mikroservis ekosistemlerinde sistem bileşenlerini birbirine bağlayan görünmez sinir ağı API (Application Programming Interface - Uygulama Programlama Arayüzü) katmanıdır. Uzun yıllar boyunca web servislerinin tartışmasız standardı olan REST (Representational State Transfer) mimarisi, günümüzde karmaşık veri grafiklerine sahip mobil istemcilerin yükselişiyle GraphQL ve yüksek frekanslı dahili mikroservis iletişiminin yaygınlaşmasıyla gRPC (Google Remote Procedure Call) gibi iki güçlü alternatifle rekabet etmektedir. Uygulama ve yazılım mimarları için REST API, GraphQL ve gRPC farkı konusunu derinlemesine anlamak; ağ bant genişliği optimizasyonu, istemci yanıt süresi (latency), tip güvenliği ve geliştirici deneyimi açısından hayati önem taşır. Bu kapsamlı teknik rehberde; Richardson Olgunluk Modeli'nden Over-Fetching ve N+1 sorgu problemine, HTTP/2 çoklamasından (multiplexing) ikili (binary) Protocol Buffers serileştirmesine kadar üç protokolü tüm mühendislik boyutlarıyla karşılaştırıyoruz.

1. REST API Nedir? Kaynak Odaklı (Resource-Oriented) Mimari ve Richardson Modeli

2000 yılında Roy Fielding'in doktora tezinde tanımladığı REST (Temsili Durum Transferi), bir protokol değil; HTTP protokolünün mevcut semantiğini (metotlar, durum kodları, önbellek başlıkları ve URI yapısı) doğrudan kullanan bir mimari stildir. REST yaklaşımında sistemdeki her varlık (Kullanıcı, Ürün, Sipariş, Fatura) benzersiz bir URI (Uniform Resource Identifier; örneğin /api/v1/orders/42) ile temsil edilen bir Kaynak (Resource) olarak modellenir.

İstemci bu kaynaklar üzerinde standart HTTP fiillerini (Verbs) kullanarak işlem yapar: GET (okuma), POST (yeni kayıt oluşturma), PUT (kaynağın tamamını güncelleme), PATCH (kısmi güncelleme) ve DELETE (silme). Sunucu ise işlemin sonucunu standart HTTP durum kodlarıyla (200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error) ve genellikle insan tarafından okunabilir JSON formatında yanıtlar.

REST'in Temel Kısıtları ve Richardson Olgunluk Modeli (Maturity Model)

• Durumsuzluk (Statelessness): Sunucu, istemcinin önceki isteklerine dair hiçbir oturum durumu (session state) saklamaz. Her HTTP isteği, işlenmesi için gereken tüm bilgiyi (örneğin Authorization: Bearer <JWT> başlığını) kendi içinde taşımak zorundadır. Bu sayede REST sunucuları yatayda kolayca ölçeklenir.
• HTTP Önbellekleme (Caching): REST, HTTP'nin yerleşik ETag, Cache-Control ve Last-Modified mekanizmalarını doğal olarak destekler. Cloudflare, Akamai veya Fastly gibi CDN katmanlarında ve tarayıcı belleğinde GET yanıtlarını sıfır ek geliştirme maliyetiyle önbelleğe almak mümkündür.
• Richardson Olgunluk Seviyeleri: Seviye 0 (Tek URI üzerinden XML/JSON gönderme), Seviye 1 (Her kaynağa ayrı URI tanımlama), Seviye 2 (Doğru HTTP metotları ve durum kodlarını kullanma - Endüstri Standardı) ve Seviye 3 (HATEOAS - Yanıt içinde istemciye bir sonraki adımda çağırabileceği linkleri dinamik olarak sunma).

REST API'nin Modern Uygulamalardaki İki Büyük Darboğazı

REST basitliği ve evrenselliği ile harika bir standart olsa da, özellikle farklı ekran boyutlarına sahip istemcilerde (Web, iOS, Android, Akıllı Saat) iki ciddi verimsizliğe yol açar:

1. Over-Fetching (Gereğinden Fazla Veri Çekme): Mobil uygulamadaki bir ürün listeleme ekranında sadece ürünün ad ve fiyat alanlarına ihtiyaç duyulduğunu düşünün. Ancak GET /api/products uç noktası (endpoint), veritabanındaki 45 farklı alanı (uzun HTML açıklamalar, teknik özellikler, tedarikçi kodları, oluşturulma tarihleri) içeren devasa bir JSON dizisi döndürür. Mobil kullanıcının internet paketi ve pil ömrü kullanılmayan verileri indirmek ve ayrıştırmak (parse etmek) için boşa harcanır.
2. Under-Fetching ve Şelale İstekler (Waterfall Network Requests): Bir kullanıcının profil ekranında "Kullanıcı Bilgileri", "Son 3 Siparişi" ve "Favori Ürünlerinin Stok Durumu" gösterilecekse; REST mimarisinde istemci önce GET /users/12, ardından GET /users/12/orders ve her ürün için GET /products//stock uç noktalarına ardışık (round-trip) HTTP istekleri atmak zorunda kalır. Yüksek gecikmeli mobil ağlarda (3G/4G) bu durum ekranın açılmasını saniyelerce geciktirir.

2. GraphQL Nedir? İstemci Güdümlü (Client-Driven) Şema ve Sorgu Dili

2012 yılında Facebook tarafından kendi mobil uygulamalarındaki karmaşık haber kaynağı (News Feed) ağ darboğazlarını çözmek için geliştirilen ve 2015'te açık kaynak haline getirilen GraphQL, API'ler için güçlü tipli (strongly-typed) bir sorgu dili (Query Language) ve sunucu tarafı çalışma zamanıdır. REST'te sunucu hangi uç noktadan hangi verinin döneceğini dikte ederken, GraphQL'de kontrol tamamen istemciye (Frontend/Mobil) geçer: "İstemci tam olarak hangi alanları istediğini sorar ve sunucudan ne bir eksik ne bir fazla, tam olarak o şekle sahip bir JSON yanıtı alır."

GraphQL mimarisinde onlarca farklı URL uç noktası yerine genellikle tek bir uç nokta (POST /graphql) bulunur ve tüm veri modeli SDL (Schema Definition Language) ile katı bir sözleşme olarak tanımlanır. Özellikle Headless Commerce ve mikroservis API mimarilerinde, arka plandaki onlarca mikroservisi tek bir birleşik veri grafiği (Federated Graph / Apollo Federation) altında toplayan BFF (Backend for Frontend) katmanı olarak altın standart haline gelmiştir.

GraphQL Temel Bileşenleri: Query, Mutation, Subscription ve N+1 Problemi

• Query (Veri Okuma): REST'teki GET karşılığıdır. İstemci, iç içe geçmiş ilişkisel nesneleri (örneğin Kullanıcı -> Siparişler -> Ürün Adı) tek bir ağ isteğinde seçerek çekebilir.
• Mutation (Veri Değiştirme): Veri ekleme, güncelleme ve silme işlemlerini (POST, PUT, DELETE karşılığı) yürütür ve işlem sonucunda güncellenen nesnenin sadece istenen alanlarını döndürür.
• Subscription (Gerçek Zamanlı Veri Akışı): WebSockets üzerinden çalışır; sunucuda bir olay gerçekleştiğinde (örneğin sipariş durumu "Kargoya Verildi" olduğunda) veriyi anlık olarak istemciye iter.
• N+1 Sorgu Problemi ve DataLoader Çözümü: GraphQL'in en kritik sunucu tarafı tuzağıdır. 20 siparişin listesini ve her siparişin müşteri adını isteyen bir GraphQL sorgusunda, dikkatsiz yazılmış bir Resolver fonksiyonu önce siparişler için 1 SQL sorgusu, ardından her siparişin müşterisi için 20 ayrı SQL sorgusu (toplam N+1 = 21 sorgu) çalıştırabilir. Bunu önlemek için DataLoader deseni kullanılarak tüm müşteri ID'leri tek bir döngüde (Event Loop Tick) toplanır (Batching) ve veritabanına SELECT * FROM customers WHERE id IN (...) şeklinde tek bir sorgu atılır.

# GraphQL İstemci Sorgusu (Tek İstekle İlişkisel Veri Seçimi - Sıfır Over-Fetching)
query GetCustomerDashboard($customerId: ID!) {
  customer(id: $customerId) {
    fullName
    loyaltyTier
    recentOrders(limit: 2) {
      orderNumber
      totalPrice
      items {
        productName
      }
    }
  }
}

3. gRPC Nedir? HTTP/2 ve Protocol Buffers (Protobuf) ile Yüksek Performans

REST ve GraphQL metin tabanlı (JSON) formatlar kullandığı için insan tarafından okunması kolaydır; ancak saniyede yüz binlerce isteğin döndüğü iç mikroservis iletişiminde (East-West Traffic) JSON metinlerini serileştirmek (serialize) ve ayrıştırmak (parse) ciddi bir CPU ve ağ bant genişliği maliyeti yaratır. Google'ın kendi veri merkezlerinde saniyede milyarlarca uzak prosedür çağrısını yönettiği Stubby altyapısının yeni nesil açık kaynaklı versiyonu olan gRPC, düşük gecikme ve maksimum veri aktarım hızı (throughput) için tasarlanmış modern bir RPC (Remote Procedure Call) çerçevesidir.

Bir mikroservisin diğerini sanki kendi yerel kodundaki bir fonksiyonu çağırıyormuş gibi (paymentClient.ProcessPayment(request)) çağırmasını sağlayan gRPC, gücünü iki temel teknolojiden alır:

1. İkili Serileştirme: Protocol Buffers (Protobuf) vs JSON

JSON metin tabanlıdır; alan adlarını (örneğin "customerBillingAddressStreetName": "Atatürk Cad.") her mesajda tekrar tekrar düz metin olarak gönderir. Protocol Buffers (Protobuf) ise dil bağımsız, ikili (binary) bir serileştirme formatıdır. Geliştirici önce bir .proto dosyasında mesaj şemasını ve her alanın sayısal etiketini (1, 2, 3) tanımlar. Veri ağ üzerinden gönderilirken uzun alan adları yerine sadece 1 baytlık alan numaraları ve sıkıştırılmış ikili değerler iletilir. Sonuç olarak Protobuf mesajları JSON'a kıyasla 3 ila 10 kat daha küçüktür ve CPU tarafından serileştirilmesi/çözülmesi 5 ila 8 kat daha hızlıdır.

// order_service.proto (Protocol Buffers Sözleşme Dosyası)
syntax = "proto3";
package ecommerce.order.v1;

service OrderService {
  rpc CreateOrder (CreateOrderRequest) returns (CreateOrderResponse);
  rpc StreamOrderStatus (OrderIdRequest) returns (stream OrderStatusUpdate);
}

message CreateOrderRequest {
  string customer_id = 1;
  repeated OrderItem items = 2;
  double total_amount = 3;
}

2. HTTP/2 Taşıma Katmanı ve 4 Farklı Akış (Streaming) Modu

Geleneksel REST API'lerin çoğunlukla kullandığı HTTP/1.1 protokolünde her eşzamanlı istek için ayrı bir TCP bağlantısı açılması gerekir veya bir istek yanıtlanmadan diğeri bekler (Head-of-Line Blocking). gRPC ise doğrudan HTTP/2 üzerinde çalışır ve şu yetenekleri sunar:

• Multiplexing (Çoklama): Tek bir TCP bağlantısı üzerinden aynı anda yüzlerce paralel istek ve yanıt, birbirini bloklamadan çift yönlü olarak iletilebilir.
• HPACK Başlık Sıkıştırması: Her istekte tekrar eden HTTP başlıkları (Headers) ikili formatta sıkıştırılarak ağ yükü azaltılır.
• 4 İletişim Modu: Sadece klasik Unary (İstek-Yanıt) değil; Server Streaming (Sunucudan kesintisiz veri akışı), Client Streaming (İstemciden kesintisiz veri/dosya akışı) ve Bidirectional Streaming (Aynı anda çift yönlü gerçek zamanlı veri akışı) doğal olarak desteklenir.

Modern kurumsal mimarilerde bu üç teknoloji birbirini dışlamaz; aksine hibrit olarak birlikte kullanılır. Örneğin bulut teknolojisi ve SaaS tabanlı bir platformda; dış iş ortaklarına ve No-Code uygulama geliştirme platformlarına açık entegrasyon uçları REST API ile sunulurken, mobil ve web ön yüzleri GraphQL ağ geçidine bağlanır; arka plandaki mikroservisler ise birbirleriyle gRPC üzerinden milisaniye altı gecikmeyle konuşur. Ayrıca eski SOAP veya belgesiz monolitik servislerin modern REST/gRPC sözleşmelerine dönüştürülmesinde yapay zeka destekli tersine mühendislik (REA) araçları ve merkeziyetsiz ağlarda Web3 ve merkezsiz web indeksleme katmanları (The Graph - Subgraphs) doğrudan GraphQL sorgu standardını kullanmaktadır.

REST API, GraphQL ve gRPC Kapsamlı Karşılaştırma Tablosu

Projenizin ihtiyaçlarına en uygun iletişim protokolünü seçebilmeniz için REST, GraphQL ve gRPC'nin teknik özelliklerini aşağıdaki tabloda karşılaştırdık:

Karşılaştırma Kriteri	REST API	GraphQL	gRPC
Mimari Yaklaşım	Kaynak Odaklı (Resource-Oriented)	Veri Grafiği ve Sorgu Odaklı (Query-Driven)	Prosedür / Fonksiyon Çağrısı (RPC)
Veri Formatı (Payload)	Metin (Çoğunlukla JSON, bazen XML)	Metin (JSON)	İkili / Binary (Protocol Buffers - Protobuf)
Taşıma Protokolü	HTTP/1.1, HTTP/2 veya HTTP/3	HTTP (Genellikle tek uç noktaya POST)	Zorunlu HTTP/2 (veya HTTP/3)
Veri Seçimi Esnekliği	Sabit (Sunucu ne dönerse istemci onu alır)	Tam Esnek (İstemci istediği alanı seçer)	Sözleşmeye Bağlı (.proto mesaj şeması)
Ağ ve CPU Performansı	Orta (JSON parse ve çoklu istek yükü)	Orta-Yüksek (Tek istekte birleşik veri)	Çok Yüksek (Binary format, 5-10x daha hızlı)
Şema ve Tip Güvenliği	Opsiyonel (OpenAPI / Swagger ile eklenir)	Zorunlu (SDL Şeması ve Introspection)	Zorunlu ve Katı (Protobuf + Otomatik Kod Üretimi)
HTTP Önbellekleme (Caching)	Mükemmel (Yerleşik HTTP GET / CDN önbelleği)	Zor (POST kullanıldığı için özel istemci gerekir)	Yok (Uygulama katmanında Redis vb. gerekir)
Tarayıcı (Browser) Desteği	%100 Doğal Destek (fetch / axios)	%100 Doğal Destek (HTTP üzerinden JSON)	Sınırlı (Tarayıcı için gRPC-Web proxy şart)
En İdeal Kullanım Alanı	Halka açık (Public) API'ler, CRUD servisleri, Webhook	Mobil uygulamalar, karmaşık SPA ekranları, BFF	Dahili mikroservis iletişimi, IoT, gerçek zamanlı akış

Hangi Senaryoda Hangi API Teknolojisi Seçilmeli?

• Ne Zaman REST API Seçilmeli? Dış dünyaya, üçüncü parti geliştiricilere veya iş ortaklarına açık (Public API) bir entegrasyon sunuyorsanız, veri modeliniz standart CRUD işlemlerine dayanıyorsa ve CDN seviyesinde HTTP önbellekleme (caching) kritikse REST + OpenAPI (Swagger) en doğru, evrensel ve öğrenme eğrisi en düşük seçenektir.
• Ne Zaman GraphQL Seçilmeli? Mobil (iOS/Android) ve Web arayüzlerinizde çok sayıda ilişkisel veriyi tek ekranda göstermeniz gerekiyorsa, ön yüz (Frontend) ekibinin her ekran değişikliğinde arka uç (Backend) ekibinden yeni endpoint beklemesini önlemek istiyorsanız ve farklı mikroservisleri tek bir BFF ağ geçidinde birleştiriyorsanız GraphQL tercih edilmelidir.
• Ne Zaman gRPC Seçilmeli? Arka planda birbirleriyle yoğun trafikli konuşan onlarca mikroservisiniz varsa, farklı dillerde (Go, Java, Python, C#, Rust) yazılmış servisler arasında otomatik istemci kodu (stub) üretmek istiyorsanız ve milisaniye altı gecikme veya çift yönlü veri akışı (streaming) gerekiyorsa gRPC rakipsizdir.

Sıkça Sorulan Sorular (SSS)

1. GraphQL, REST API'nin tamamen yerini mi alacak?

Hayır. GraphQL, REST'in yerini almak için değil, REST'in karmaşık ve iç içe geçmiş veri modellerinde yaşadığı Over-Fetching/Under-Fetching sorunlarını çözmek için geliştirilmiştir. Basit kaynak yönetiminde, dosya indirme/yükleme işlemlerinde, HTTP CDN önbelleklemesinde ve üçüncü parti kurumsal B2B entegrasyonlarında REST API hala dünyanın en yaygın ve en pratik standardıdır.

2. Web tarayıcılarından (React, Vue, Angular) doğrudan gRPC çağrılabilir mi?

Modern web tarayıcılarındaki standart JavaScript fetch veya XMLHttpRequest API'leri, gRPC'nin ihtiyaç duyduğu alt seviye HTTP/2 çerçeve (frame) kontrollerine ve trailing headers yapılarına doğrudan erişim izni vermez. Bu nedenle tarayıcıdan gRPC servislerini çağırmak için araya Envoy Proxy gibi bir çevirici koyan gRPC-Web protokolü veya hem tarayıcı hem gRPC uyumlu ConnectRPC standardı kullanılmalıdır.

3. GraphQL'de güvenlik ve yetkilendirme (Rate Limiting) neden REST'ten daha zordur?

REST API'de her işlem ayrı bir URL olduğu için /api/login uç noktasına dakikada 5 istek sınırı koymak çok kolaydır. GraphQL'de ise tüm istekler tek bir /graphql adresine gelir ve kötü niyetli bir kullanıcı tek bir HTTP isteği içinde 10 katman derinliğinde iç içe geçmiş (nested query) devasa bir sorgu göndererek sunucuyu kilitleyebilir (DoS saldırısı). Bunu önlemek için GraphQL sunucularında mutlaka Query Depth Limiting (Sorgu Derinliği Sınırı), Query Complexity Analysis (Maliyet Analizi) ve üretim ortamında Introspection kapatma önlemleri alınmalıdır.

4. gRPC'de şema değiştiğinde (yeni alan eklendiğinde) eski istemciler bozulur mu?

Protocol Buffers (Protobuf) ileriye ve geriye dönük uyumluluk (Forward & Backward Compatibility) için özel olarak tasarlanmıştır. Mevcut alanların sayısal etiketlerini (= 1, = 2) değiştirmediğiniz ve silinen alan numaralarını reserved olarak işaretlediğiniz sürece, .proto dosyasına yeni alanlar eklediğinizde eski istemciler bilmedikleri yeni alanları sessizce yok sayar ve hiçbir kesinti olmadan çalışmaya devam eder.

5. Aynı projede hem REST, hem GraphQL, hem gRPC birlikte kullanılabilir mi?

Evet, hatta büyük ölçekli teknoloji şirketlerinin standart mimarisi tam olarak budur. Arka uçtaki mikroservisler kendi aralarında maksimum hız için gRPC ile haberleşir; mobil ve web uygulamalarının bağlandığı API Gateway / BFF katmanı esnek veri sorgulama için GraphQL sunar; dış dünyadaki ödeme sağlayıcıları ve B2B iş ortakları için ise standart REST API uç noktaları (Webhook'lar dahil) açık tutulur.