GraphQL Federation ve API Birlestirme Rehberi [2026]

GraphQL Federation Nedir ve Neden Onemlidir

Mikroservis mimarileri yayginlastikca, her servisin kendi API katmanini sunmasi karmasik bir entegrasyon sorununa donustu. Istemci tarafinda onlarca endpoint ile iletisim kurmak, veri birlestirme islemlerini frontend katmanina yiklemek ve tutarli bir API deneyimi saglamak giderek zorlasti. GraphQL Federation, bu soruna yapisal bir cozum sunar.

GraphQL Federation, birden fazla bagimsiz GraphQL servisini (subgraph) tek bir birlesik schema (supergraph) altinda toplayan bir mimari yaklasimdir. Her takim kendi subgraph'ini bagimsiz olarak gelistirir, deploy eder ve yonetir. Gateway katmani ise gelen sorgulari analiz ederek ilgili subgraph'lara yonlendirir ve sonuclari birlestirerek istemciye tek bir yanit dondurur.

Apollo Federation v2, bu alanda fiili standart haline gelmistir. Ilk surume kiyasla onemli iyilestirmeler sunar: @shareable direktifi ile birden fazla subgraph'in ayni alani sunabilmesi, @override ile alan sahipliginin transfer edilmesi ve @inaccessible ile dahili alanlarin supergraph'tan gizlenebilmesi gibi yetenekler eklenmistir.

Monolithic GraphQL ve Federated GraphQL Karsilastirmasi

Monolitik ve federated yaklasimlar arasindaki farklari net olarak anlamak, dogru mimari karari vermek icin kritiktir.

Kriter	Monolithic GraphQL	Federated GraphQL
Schema yonetimi	Tek buyuk schema dosyasi	Dagitik subgraph schemalari
Takim bagimsizligi	Dusuk, tek repo baglimliligi	Yuksek, her takim kendi subgraph'ini yonetir
Deploy sureci	Tum schema birlikte deploy edilir	Subgraph'lar bagimsiz deploy edilir
Olceklenebilirlik	Dikey olceklendirme	Yatay, subgraph bazinda olceklendirme
Performans overhead	Dusuk, tek servis	Orta, gateway ve network hop maliyeti
Karmasiklik	Baslangicta dusuk	Baslangicta yuksek, olcekte dusuk
Hata izolasyonu	Tek hata noktasi	Subgraph bazinda izolasyon

Kucuk ve orta olcekli projelerde monolitik GraphQL yeterli olabilir. Ancak birden fazla takimin calistigi, farkli deploy dongulerinin gerektigi ve servislerin bagimsiz olceklenmesi gereken ortamlarda federation kacinilmaz hale gelir.

Subgraph Tasarimi ve Entity Resolution

Federation mimarisinin temel yapi tasi subgraph'lardir. Her subgraph, belirli bir is alanini (domain) temsil eder ve kendi GraphQL schemasini tanimlar. Iyi bir subgraph tasarimi icin su ilkelere dikkat edilmelidir:

Domain Boundary Belirleme

Subgraph sinirlari, is alani sinirlarini takip etmelidir. Ornegin bir e-ticaret platformunda:

• Users Subgraph: Kullanici yonetimi, profil, adresler
• Products Subgraph: Urun katalogu, kategoriler, stok
• Orders Subgraph: Siparis yonetimi, siparis durumu
• Reviews Subgraph: Urun degerlendirmeleri, puanlama

Entity Tanimlama

Entity'ler, subgraph'lar arasinda paylasilan ve referans edilen tiplerdir. Bir entity, bir subgraph'ta tanimlanir ve diger subgraph'lar tarafindan genisletilir:

# Users Subgraph
type User @key(fields: "id") {
  id: ID!
  name: String!
  email: String!
  createdAt: DateTime!
}

# Orders Subgraph - User entity'sini genisletir
type User @key(fields: "id") {
  id: ID!
  orders: [Order!]!
  totalSpent: Float!
}

type Order @key(fields: "id") {
  id: ID!
  user: User!
  items: [OrderItem!]!
  status: OrderStatus!
  createdAt: DateTime!
}

Entity Resolution

Gateway bir sorguyu islerken, farkli subgraph'lardan gelen verileri birlestirmek icin entity resolution mekanizmasini kullanir. Her subgraph, sahip oldugu entity'ler icin bir __resolveReference fonksiyonu tanimlar:

// Users Subgraph - reference resolver
const resolvers = {
  User: {
    __resolveReference(reference) {
      // reference.id ile kullaniciyi veritabanindan getir
      return usersService.findById(reference.id);
    }
  }
};

Bu mekanizma sayesinde gateway, User entity'sinin id alanini kullanarak ilgili subgraph'tan tam veriyi ceker ve diger subgraph'lardan gelen verilerle birlestirir.

Schema Composition ve Supergraph

Schema composition, birden fazla subgraph schemasinin tek bir supergraph schema'ya donusturulme surrecidir. Bu islem build zamaninda gerceklesir ve olusturulan supergraph schema dosyasi gateway'e yuklenir.

Composition Sureci

# Apollo Rover CLI ile schema composition
rover supergraph compose --config ./supergraph-config.yaml > supergraph.graphql

# supergraph-config.yaml ornegi
federation_version: =2.7
subgraphs:
  users:
    routing_url: http://users-service:4001/graphql
    schema:
      file: ./schemas/users.graphql
  products:
    routing_url: http://products-service:4002/graphql
    schema:
      file: ./schemas/products.graphql
  orders:
    routing_url: http://orders-service:4003/graphql
    schema:
      file: ./schemas/orders.graphql

Composition Hatalari ve Cozumleri

Schema composition sirasinda en sik karsilasilan hatalar ve cozumleri:

• FIELD_TYPE_MISMATCH: Ayni alanin farkli subgraph'larda farkli tiplerle tanimlanmasi. Cozum olarak @shareable direktifi ile ortak alanlari isaretleyin.
• EXTERNAL_MISSING_ON_BASE: Bir subgraph'ta @external olarak isaretlenen alanin kaynak subgraph'ta bulunmamasi. Kaynak subgraph'taki schema'yi kontrol edin.
• OVERRIDE_COLLISION: Birden fazla subgraph'in ayni alani override etmeye calismasi. Alan sahipligini netlestirin.

Composition islemini CI/CD pipeline'ina entegre ederek, her subgraph degisikliginde otomatik dogrulama yapmak onemlidir. Bu sayede uyumsuz degisiklikler uretim ortamina ulasmadan tespit edilir.

Gateway ve Router Secenekleri

Gateway, federation mimarisinin merkezi bilesenidir. Gelen GraphQL sorgularini analiz eder, query plan olusturur ve ilgili subgraph'lara dagitir.

Apollo Router

Apollo Router, Rust tabanli yuksek performansli bir gateway cozumudur. Apollo Federation v2 ile tam uyumlu calisir ve production ortamlari icin onerilir:

# router.yaml konfigurasyonu
supergraph:
  listen: 0.0.0.0:4000
  path: /graphql

headers:
  all:
    request:
      - propagate:
          named: "authorization"
      - propagate:
          named: "x-request-id"

telemetry:
  instrumentation:
    spans:
      mode: spec_compliant
  exporters:
    tracing:
      otlp:
        enabled: true
        endpoint: http://otel-collector:4317

traffic_shaping:
  all:
    timeout: 30s
  subgraphs:
    products:
      timeout: 10s

GraphQL Mesh

GraphQL Mesh, farkli veri kaynaklarini (REST, gRPC, SOAP, veritabanlari) GraphQL olarak birlestirme yetenegine sahip bir alternatiftir. Ozellikle mevcut REST API'lerin federation'a dahil edilmesi gerektiginde guclu bir secenektir:

# .meshrc.yaml
sources:
  - name: LegacyREST
    handler:
      openapi:
        source: ./openapi-spec.yaml
        baseUrl: http://legacy-api:3000
  - name: ProductsGraphQL
    handler:
      graphql:
        endpoint: http://products-service:4002/graphql

Smart Maple olarak Ankara merkezli projelerimizde, mevcut REST API altyapilarini GraphQL federation'a gecirirken GraphQL Mesh'i gecis katmani olarak siklikla kullaniyoruz.

Performans Optimizasyonu

Federation mimarisinde performans, birden fazla network hop ve veri birlestirme islemleri nedeniyle ozenle yonetilmesi gereken bir konudur.

Query Planning

Gateway, gelen her sorgu icin bir query plan olusturur. Bu plan, hangi subgraph'larin hangi sirada cagirilacagini ve verilerin nasil birlestirilecegini belirler. Iyi tasarlanmis bir schema, paralel calisabilecek subgraph cagrilarini maksimize eder:

# Verimli sorgu - paralel fetch mumkun
query {
  user(id: "123") {
    name          # Users subgraph
    email         # Users subgraph
  }
  products(limit: 10) {
    title         # Products subgraph
    price         # Products subgraph
  }
}

# Seri bagimllik gerektiren sorgu
query {
  user(id: "123") {
    name          # 1. Users subgraph
    orders {      # 2. Orders subgraph (User entity resolution gerekir)
      items {
        product {
          title   # 3. Products subgraph (Product entity resolution gerekir)
        }
      }
    }
  }
}

DataLoader Pattern

N+1 sorgu problemini onlemek icin DataLoader pattern'i her subgraph'ta uygulanmalidir:

const DataLoader = require('dataloader');

const userLoader = new DataLoader(async (ids) => {
  const users = await db.users.findMany({
    where: { id: { in: ids } }
  });
  // ID sirasina gore sirala
  return ids.map(id => users.find(u => u.id === id));
});

const resolvers = {
  User: {
    __resolveReference(ref) {
      return userLoader.load(ref.id);
    }
  }
};

Cache Stratejileri

Cache Katmani	Uygun Senaryo	TTL Onerisi
CDN / Edge Cache	Statik veya nadir degisen veriler	5-60 dakika
Gateway Response Cache	Sikca tekrarlanan sorgular	1-5 dakika
Subgraph Cache (Redis)	Entity bazinda onbellekleme	1-30 dakika
DataLoader (Request-scoped)	Ayni request icinde tekrarlanan cagrilar	Request suresi

Gateway seviyesinde Automatic Persisted Queries (APQ) kullanarak sorgu metinlerinin her istekte gonderilmesini onleyebilir, network trafikini onemli olcude azaltabilirsiniz.

Federation ve Schema Stitching Farklari

Schema stitching, federation oncesinde birden fazla GraphQL schemasini birlestirmek icin kullanilan yaklasimdi. Iki yaklasim arasindaki temel farklar:

Ozellik	Schema Stitching	Federation
Schema sahipligi	Merkezi gateway tanimlar	Her subgraph kendi schemasini tanimlar
Entity resolution	Gateway'de resolver delegation	Subgraph'larda __resolveReference
Bagimsizlik	Dusuk, gateway bagimli	Yuksek, subgraph bagimsiz
Standartlasma	Her implementasyon farkli	Apollo Federation spec standart
Tooling	Sinirli	Zengin ekosistem (Rover, Studio)
Performans	Resolver delegation overhead	Optimize edilmis query planning

Federation, schema stitching'in evrimsel bir sonraki adimi olarak dusunulebilir. Yeni projeler icin federation tercih edilmelidir. Mevcut schema stitching kullanan projeler icin ise kademeli bir gecis plani olusturulmalidir.

Authentication ve Authorization

Federated bir GraphQL mimarisinde kimlik dogrulama ve yetkilendirme, katmanli bir yaklasimla uygulanmalidir.

Gateway Katmaninda Authentication

Gateway, gelen her istekteki JWT token'i dogrular ve kullanici bilgilerini subgraph'lara iletir:

// Gateway middleware
const authenticateRequest = async (req) => {
  const token = req.headers.authorization?.replace('Bearer ', '');
  if (!token) return { authenticated: false };

  try {
    const decoded = await verifyJWT(token);
    return {
      authenticated: true,
      userId: decoded.sub,
      roles: decoded.roles,
      permissions: decoded.permissions
    };
  } catch (error) {
    return { authenticated: false };
  }
};

Subgraph Katmaninda Authorization

Her subgraph, kendi alanindaki yetkilendirme kurallarini uygular. Federation v2 ile @authenticated ve @requiresScopes direktifleri kullanilabilir:

# Products Subgraph
type Product @key(fields: "id") {
  id: ID!
  title: String!
  price: Float!
  costPrice: Float! @requiresScopes(scopes: [["admin"], ["finance"]])
  internalNotes: String @requiresScopes(scopes: [["admin"]])
}

type Mutation {
  createProduct(input: ProductInput!): Product! @authenticated
  deleteProduct(id: ID!): Boolean! @requiresScopes(scopes: [["admin"]])
}

Bu katmanli yaklasim, authentication'in merkezi olarak yapilmasini ve authorization'in ise ilgili domain'e yakin tutulmasini saglar.

Monitoring ve Observability

Dagitik bir federation mimarisinde gozlemlenebilirlik, sorun tespiti ve performans iyilestirmesi icin kritik oneme sahiptir.

Temel Metrikler

Izlenmesi gereken kritik metrikler sunlardir:

• Query plan suresi: Gateway'in sorgu planini olusturma suresi
• Subgraph yanit suresi: Her subgraph'in ortalama ve p99 yanit suresi
• Entity resolution suresi: Entity cozumleme operasyonlarinin suresi
• Hata oranlari: Subgraph bazinda hata oranlari ve tipleri
• Cache hit orani: Her cache katmanindaki isabet orani

Distributed Tracing

OpenTelemetry entegrasyonu ile uctan uca izlenebilirlik saglanabilir:

// Subgraph'ta OpenTelemetry entegrasyonu
const { trace } = require('@opentelemetry/api');

const tracer = trace.getTracer('products-subgraph');

const resolvers = {
  Query: {
    product: async (_, { id }, context) => {
      const span = tracer.startSpan('resolve-product', {
        attributes: {
          'graphql.field': 'product',
          'product.id': id,
          'request.id': context.requestId
        }
      });
      try {
        const result = await productService.findById(id);
        span.setStatus({ code: SpanStatusCode.OK });
        return result;
      } catch (error) {
        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
        throw error;
      } finally {
        span.end();
      }
    }
  }
};

Apollo Studio veya Grafana + Tempo gibi araclarla, bir GraphQL sorgusunun gateway'den subgraph'lara kadar tum yolculugunu gorsellestirebilirsiniz.

REST'ten Federated GraphQL'e Gecis Stratejisi

Mevcut REST API altyapisindan federated GraphQL'e gecis, buyuk bir donusumu ifade eder. Bu gecisi basarili kilmak icin kademeli bir strateji izlenmelidir.

Asamali Gecis Plani

Asama 1 - Analiz ve Planlama (2-4 hafta): Mevcut REST endpoint'lerini haritalandirin. Domain sinirlarini belirleyin ve subgraph planini olusturun. Takim yetkinliklerini degerlendirin.

Asama 2 - Pilot Subgraph (4-6 hafta): En az bagimliliga sahip bir domain secin. Ilk subgraph'i olusturun ve gateway'i kurun. CI/CD pipeline'ini yapilandirin.

Asama 3 - Kademeli Genisleme (sureklii): Diger domainleri birer birer subgraph olarak ekleyin. REST endpoint'lerini GraphQL Mesh ile sarmalayarak gecis surecinde iki API'yi paralel calistirin.

Asama 4 - REST Decommission: Tum istemciler GraphQL'e gectiginde eski REST endpoint'lerini kaldirabilisiniz. Bu asama genellikle en uzun suren asamadir.

Dikkat Edilmesi Gerekenler

Smart Maple olarak Ankara merkezli projelerimizde edindigimiz deneyimlerden yola cikarak, gecis surecinde su noktalarin kritik oldugunu soyleyebiliriz:

• Istemci takimlarini erken dahil edin; sorgu ihtiyaclarini anlayin
• Mevcut REST API'leri hemen kapatmayin, gecis suresi taniyin
• Schema tasarimini REST endpoint yapisina degil, is alani modellerine dayandirin
• Her subgraph icin ayri veritabani erisimi saglayin; paylasilan veritabani anti-pattern'dir
• Load testing'i erken baslatin; federation overhead'ini olcun

Sonuc

GraphQL Federation, mikroservis mimarilerinde API katmanini birlestirmenin en olgun ve standartlasmis yoludur. Subgraph bazinda takim bagimsizligi, esnek schema composition ve guclu tooling ekosistemi ile buyuk olcekli projelerde onemli avantajlar saglar.

Basarili bir federation uygulamasi icin domain sinirlarinin dogru belirlenmesi, entity resolution stratejilerinin optimize edilmesi ve katmanli bir guvenlik modelinin olusturulmasi gerekir. Monitoring ve observability altyapisi ise dagitik mimarinin saglikli islemesini garanti altina alir.

REST'ten federation'a gecis surecinde sabir ve kademeli ilerleme esastir. Her asamada olcun, degerlendirin ve bir sonraki adima gecin. Dogru planlanmis bir gecis, hem gelistirici deneyimini hem de son kullanici performansini onemli olcude iyilestirir.