API Tasarimi: REST, GraphQL ve gRPC Gercek Dunyada

Modern bir API tasarimi yaparken REST, GraphQL ve gRPC arasinda secim yapmak, cogu zaman hangisinin en populer olduguna veya ekibin en cok hangisine asina olduguna gore sekillenir. Ancak her birinin altinda yatan farkli kabuller ve odunlesmeler vardir.

Hizli karar vermek gerekirse: REST, harici API ler icin en iyi secenek olmaya devam ediyor, GraphQL bilesik veri gereksinimleri olan istemciler (mobil ve SPA) icin idealdir ve gRPC, ic servis iletisimi icin, ozellikle yuksek performansli mikroservis mimarilerinde en uygunudur. Ancak bu genellemelerin altinda, seciminizi yonlendirecek daha spesifik faktorler vardir.

REST: Basitlik ve olgunluk

REST (Representational State Transfer), kaynaklara dayali bir modeldir. Her URL bir kaynagi temsil eder ve HTTP metodlari (GET, POST, PUT, DELETE) o kaynak uzerinde islem yapmak icin kullanilir. REST in en buyuk avantaji basitligi ve evrenselligidir. HTTP uzerinde calisan her istemci, bir REST API ile iliskilendirilebilir.

Ancak REST in basitligi, buyuk ve ekipli projelerde bazi zorluklari da beraberinde getirir. Over-fetching (gereginden fazla veri gelmesi) ve under-fetching (yeterli veri gelmemesi) REST in en sik karsilasilan sorunlaridir. Bir kullanicinin profilini ve son siparislerini almak icin iki ayri API cagrisi yapmak zorunda kalmak, mobil uygulamalarda gecikmeyi artiran bir etkendir.

REST te en iyi uygulamalar

• Kaynak adlarini cogul kullanin: /users, /orders, /products.
• HTTP durum kodlarini dogru kullanin: 200 basarili, 201 olusturma, 204 icerik yok, 400 gecersiz istek, 404 bulunamadi, 500 sunucu hatasi.
• Versiyonlama icin URL veya header kullanin: /v1/users veya Accept: application/vnd.api.v1+json.
• Filtreleme, siralama ve sayfalama icin query parametreleri kullanin: ?status=active&sort=created_at&page=2&limit=20.
• Hata mesajlarini standart bir formatta donun: { error: { code: "NOT_FOUND", message: "Kullanici bulunamadi" } }.
• Govde degil, HTTP metodlarini semantik olarak kullanin. Bir kullanicinin e-posta adresini guncellemek icin PATCH /users/123 kullanin, POST /users/123/update-email degil.

REST API ler icin dokumantasyon, Swagger/OpenAPI ile standartlastirilir. OpenAPI, API nizin semasini, ornek istekleri ve yanitlari iceren bir spesifikasyon dosyasi olusturmaniza olanak tanir. Bu dosyadan otomatik olarak istemci SDK lari ve test araclari da olusturulabilir.

GraphQL: Esneklik ve verimlilik

GraphQL, istemcinin ihtiyac duydugu veriyi belirlemesine olanak taniyan bir sorgu dilidir. Bir GraphQL API si, tek bir uc noktaya (genellikle /graphql) sahiptir ve istemci, ihtiyac duydugu alanlari belirten bir sorgu gonderir. Sunucu, yalnizca istenen alanlari iceren bir yanit doner.

GraphQL in en buyuk avantaji, over-fetching ve under-fetching sorununu cozmesidir. Bir mobil uygulama, bir kullanicinin yalnizca adini ve e-posta adresini isteyebilirken, bir web uygulamasi ayni kullanici icin ek alanlar isteyebilir. Tek bir uc nokta sayesinde istemci, ihtiyaci kadar veri alir.

Ancak GraphQL in kendi zorluklari vardir. Sorgu karmasikligi, bir istemcinin cok derin veya cok genis bir sorgu gondererek sunucuya asiri yuklenmesine neden olabilir. Sorgu maliyeti analizi (query costing) ve derinlik sinirlamasi (depth limiting) gibi mekanizmalar, bu sorunu onlemek icin kullanilmalidir.

GraphQL API lerinde N+1 sorgu problemi, REST te oldugundan daha sik gorulur. Cozum olarak DataLoader gibi toplu yukleme araclari kullanilir. DataLoader, ayni istek icinde ayni turden birden fazla veri tabani sorgusunu toplar ve tek bir sorguda birlestirir.

// Without DataLoader: N+1 problem
const resolvers = {
  Post: {
    author: async (post) => {
      // Called once per post — N queries for N posts
      return db.user.findUnique({ where: { id: post.authorId } });
    },
  },
};

// With DataLoader: batched
const userLoader = new DataLoader(async (ids: number[]) => {
  const users = await db.user.findMany({ where: { id: { in: ids } } });
  return ids.map((id) => users.find((u) => u.id === id));
});

const resolvers = {
  Post: {
    author: async (post) => userLoader.load(post.authorId),
  },
};

GraphQL in bir diger avantaji, tip sistemidir. Her GraphQL API si bir sema ile tanimlanir ve bu sema, API nin yeteneklerini ve veri tiplerini acikca belirtir. Bu sema, istemci ve sunucu arasinda bir sozlesme gorevi gorur ve tip guvenligini saglar.

gRPC: Performans ve tip guvenligi

gRPC, Google tarafindan gelistirilen, Protocol Buffers tabanli bir uzak cagri (RPC) cercevesidir. REST ve GraphQL in aksine, gRPC HTTP/2 uzerinden calisir ve protobuf adli ikili bir serilestirme formati kullanir. Bu sayede hem daha hizli hem de daha az ag bant genisligi tuketir.

gRPC, ozellikle mikroservis mimarilerinde servisler arasi iletisim icin idealdir. Iki servis arasinda yuksek frekansli cagrilar varsa, gRPC in REST e kiyasla 5-10 kat daha hizli oldugu gorulmustur. Ayrica, gRPC streaming destegi sayesinde, sunucudan istemciye veya iki yonlu surekli veri akisi saglanabilir.

gRPC nin en buyuk zorlugu, tarayici desteginin sinirli olmasidir. Bir REST API sine herhangi bir tarayicidan dogrudan istek gonderebilirken, gRPC icin genellikle bir proxy (grpc-web) gerekir. Bu nedenle gRPC, dis dunyaya acik API ler icin degil, ic servis iletisimi icin daha uygundur.

Gercek dunyada karsilastirma

Her uc paradigmayi gercek bir senaryoda karsilastiralim: bir e-ticaret platformu. Platformun hem web hem mobil istemcileri var, ayrica ic servisler (siparis, odeme, envanter) birbirleriyle iletisim kuruyor.

• Harici API (partner entegrasyonlari): REST. Partnerlerin GraphQL veya gRPC ogrenmesini gerektirmeyin. REST, herkesin anlayabilecegi bir standarttir.
• Web ve mobil istemciler: GraphQL. Mobil uygulamanin, bir sayfada birden cok kaynaktan veri almasini saglamak icin GraphQL idealdir.
• Servisler arasi iletisim: gRPC. Yuzlerce mikroservis arasinda saniyede milyonlarca istegini gRPC ile iletmek, REST e gore cok daha verimlidir.
• Gercek zamanli bildirimler: gRPC streaming. Siparis durumu guncellemeleri gibi surekli veri akisi gerektiren durumlar icin gRPC streaming idealdir.

Gercek dunyada API secimi, bir paradigma secimi degil, bir stratejidir. Her birinin kendi guclu ve zayif yonleri vardir ve en iyi cozum genellikle hepsini bir arada kullanmaktir.