API Nedir? REST, GraphQL ve WebSocket Farkını Gerçek Örneklerle Anlamak

API Nedir?

API, “Application Programming Interface” ifadesinin kısaltmasıdır. Türkçeye “Uygulama Programlama Arayüzü” olarak çevrilebilir. En sade haliyle API, bir yazılımın başka bir yazılıma hangi kurallarla istek gönderebileceğini ve karşılığında nasıl cevap alacağını tanımlar.

Günlük hayattan klasik bir benzetme yapmak gerekirse API, restorandaki menü ve garson gibi düşünülebilir. Sen mutfağa girip yemeği kendin yapmazsın. Menüden ne istediğini seçersin, garson siparişi mutfağa iletir, mutfak da sonucu sana döndürür. Yazılım dünyasında da mobil uygulama, tarayıcı veya başka bir servis doğrudan veritabanına girmez; API’ye istek gönderir, API de kurallara uygun cevabı döner.

Fakat API’yi sadece bu benzetmeyle bırakmak eksik olur. Gerçek yazılım dünyasında API; veri güvenliği, kullanıcı yetkisi, performans, canlı veri akışı, mobil uygulama entegrasyonu, üçüncü parti servis bağlantıları ve otomasyon gibi birçok konunun merkezinde yer alır.

İstemci ve Sunucu Mantığı

API’yi anlamanın en önemli adımı istemci ve sunucu ilişkisini anlamaktır. İstemci; tarayıcı, mobil uygulama, masaüstü programı veya başka bir servis olabilir. Sunucu ise veriyi saklayan, işleyen ve kurallara göre cevap dönen taraftır.

Örneğin bir hava durumu uygulamasını açtığında telefonun istemci olur. Uygulama sunucuya “İzmir için bugünkü hava durumu nedir?” diye istek gönderir. Sunucu hava durumu verisini işler ve uygulamaya JSON gibi yapılandırılmış bir cevap döner. Uygulama da bu cevabı ekranda sıcaklık, rüzgar ve yağış bilgisi olarak gösterir.

Endpoint, Request ve Response Ne Demek?

API dünyasında sık duyacağın üç kavram vardır: endpoint, request ve response. Endpoint, API içinde belirli bir iş için kullanılan adrestir. Request, istemcinin gönderdiği istektir. Response ise sunucunun döndürdüğü cevaptır.

İstemci:
GET /haberler

Sunucu:
[
  {
    "id": 1,
    "baslik": "Yeni teknoloji haberi",
    "kategori": "Teknoloji"
  },
  {
    "id": 2,
    "baslik": "Yapay zeka gelişmesi",
    "kategori": "Yapay Zeka"
  }
]

Burada GET /haberler bir endpoint isteğidir. Sunucu da haberleri JSON formatında döndürür. Frontend tarafı bu JSON verisini alır ve kullanıcıya kart, liste veya tablo olarak gösterir.

REST API Nedir?

REST, web dünyasında en yaygın API yaklaşımıdır. REST API’de veriler genellikle “resource”, yani kaynak mantığıyla düşünülür. Haberler, kullanıcılar, siparişler, ürünler, yorumlar veya stok kayıtları birer kaynak gibi ele alınır. Bu kaynaklar URL’ler üzerinden temsil edilir.

REST API’nin gücü sadeliğinden gelir. HTTP metotlarıyla ne yapmak istediğini belirtirsin: veri almak için GET, yeni kayıt oluşturmak için POST, var olan kaydı güncellemek için PUT veya PATCH, silmek için DELETE kullanılır.

# Haberleri listele
GET /haberler

# ID'si 15 olan haberi getir
GET /haberler/15

# Yeni sipariş oluştur
POST /siparisler

# ID'si 7 olan kullanıcıyı güncelle
PUT /kullanicilar/7

# ID'si 22 olan yorumu sil
DELETE /yorumlar/22

REST özellikle CRUD işlemlerinde çok rahattır. CRUD; Create, Read, Update, Delete anlamına gelir. Yani oluşturma, okuma, güncelleme ve silme işlemleri. Bir yönetim paneli, haber sitesi, stok takip sistemi, bayi portalı veya mobil uygulama backend’i için REST çoğu zaman çok iyi bir başlangıçtır.

REST API Gerçek Dünya Örnekleri

REST’i gerçek örneklerle düşünmek çok daha kolaydır. Bir haber sitesinde kategoriye göre içerik çekmek, bir e-ticaret sitesinde sipariş oluşturmak, bir mobil uygulamada kullanıcı profilini güncellemek veya bir stok takip sisteminde ürün listesini almak REST ile gayet doğal çözülebilir.

REST’in Güçlü ve Zayıf Tarafları

REST’in en güçlü tarafı yaygın, anlaşılır ve öğrenmesi kolay olmasıdır. Hemen hemen her programlama dili, framework, test aracı ve API platformu REST ile rahat çalışır. Bu yüzden yeni başlayan biri için API öğrenmenin en doğru başlangıç noktası çoğu zaman REST’tir.

Ancak REST her zaman mükemmel çözüm değildir. Bazen istemci ihtiyacından fazla veri alır. Bazen de ihtiyacı olan tüm veriyi toplamak için birden fazla endpoint çağırmak zorunda kalır. Örneğin bir kullanıcı profil ekranı için kullanıcı bilgisi, son siparişler, favoriler, bildirimler ve yetkiler ayrı endpoint’lerden geliyorsa, frontend tarafında çok fazla istek oluşabilir.

GraphQL Nedir?

GraphQL, API tarafında farklı bir bakış açısı sunar. REST’te endpoint genellikle ne döneceğini büyük ölçüde belirler. GraphQL’de ise istemci, hangi veriye ihtiyacı olduğunu sorgu içinde açıkça söyler. Yani “sunucu ne verirse onu alayım” yerine “ben şu alanları istiyorum” mantığı öne çıkar.

Bu özellikle karmaşık veri yapılarında çok işe yarar. Örneğin kullanıcı profil ekranında sadece kullanıcının adı, e-posta adresi ve son üç siparişi gerekiyorsa, GraphQL sorgusu sadece bu alanları isteyebilir. Gereksiz alanlar gelmez, eksik alan için ikinci istek atmak da çoğu zaman gerekmez.

query {
  kullanici(id: 7) {
    ad
    eposta
    sonSiparisler(limit: 3) {
      id
      tarih
      toplamTutar
    }
  }
}

Bu sorgu şunu söyler: “ID’si 7 olan kullanıcının adını, e-posta adresini ve son 3 siparişinin id, tarih ve toplam tutar bilgisini getir.” Eğer kullanıcının adresi, telefon numarası veya tüm sipariş detayları gerekmiyorsa bunlar istenmez.

GraphQL Gerçek Dünya Örnekleri

GraphQL özellikle bir ekranda farklı veri parçalarının birlikte gösterildiği sistemlerde çok kullanışlıdır. Büyük yönetim panelleri, kullanıcı dashboard’ları, raporlama ekranları, mobil uygulamalar ve çok ilişkili veri yapıları buna örnektir.

GraphQL’in Güçlü ve Zayıf Tarafları

GraphQL’in güçlü tarafı esnekliktir. Frontend ekibi hangi veriye ihtiyacı olduğunu daha net ifade edebilir. Backend tarafında çok sayıda küçük endpoint tasarlamak yerine daha merkezi bir sorgulama modeli kurulabilir.

Ancak GraphQL de her derde deva değildir. Sunucu tarafı tasarımı daha dikkat ister. Yetkilendirme, sorgu karmaşıklığı, performans, cache stratejisi ve veri modelinin doğru kurulması önemlidir. Basit bir blog listesi veya temel CRUD paneli için GraphQL bazen gereğinden fazla karmaşık olabilir.

WebSocket Nedir?

REST ve GraphQL çoğunlukla “istek gönder, cevap al” mantığıyla çalışır. WebSocket ise farklıdır. WebSocket bağlantısında istemci ile sunucu arasında sürekli açık kalan çift yönlü bir kanal kurulur. Böylece sunucu da istemciye anlık veri gönderebilir.

Bunu canlı mesajlaşma uygulaması üzerinden düşünelim. REST ile her birkaç saniyede bir “yeni mesaj var mı?” diye sunucuya sormak gerekir. Bu yöntem çalışır ama verimsizdir. WebSocket’te ise bağlantı açık kalır. Yeni mesaj geldiği anda sunucu bunu istemciye iletebilir.

const socket = new WebSocket("wss://api.example.com/live");

socket.onopen = () => {
  console.log("Canlı bağlantı açıldı.");
};

socket.onmessage = (event) => {
  const veri = JSON.parse(event.data);
  console.log("Yeni veri geldi:", veri);
};

socket.onclose = () => {
  console.log("Bağlantı kapandı.");
};

Burada tarayıcı sunucuya bir WebSocket bağlantısı açar. Bağlantı açık kaldığı sürece sunucu yeni veri gönderebilir. Bu yapı canlı sohbet, anlık borsa fiyatı, canlı maç skoru, oyun, araç takip sistemi ve anlık bildirimler için çok uygundur.

WebSocket Gerçek Dünya Örnekleri

WebSocket’in en net anlaşıldığı yerler gerçek zamanlı uygulamalardır. Eğer veri sürekli değişiyor ve kullanıcı bunu anlık görmeli ise WebSocket güçlü bir seçenektir.

REST, GraphQL ve WebSocket Farkı

Bu üç yaklaşımı birbirinin rakibi gibi değil, farklı ihtiyaçlara cevap veren araçlar gibi düşünmek daha doğrudur. REST düzenli veri alışverişinde güçlüdür. GraphQL karmaşık veri ihtiyaçlarında esneklik sağlar. WebSocket ise anlık veri akışı gereken yerlerde öne çıkar.

Gerçek Senaryoda Hangisi Kullanılır?

Teoriyi anlamak güzel ama asıl öğrenme gerçek senaryolarla olur. Aşağıdaki tablo, farklı yazılım ihtiyaçlarında hangi API yaklaşımının daha uygun olabileceğini gösterir.

Bir Uygulamada Üçü Birden Kullanılabilir mi?

Evet, kullanılabilir. Hatta modern uygulamalarda bu oldukça normaldir. Bir sistemde REST, GraphQL ve WebSocket aynı anda farklı görevler üstlenebilir. Önemli olan her işi doğru yaklaşımla çözmektir.

Örneğin bir stok takip ve bayi portalı düşünelim. Ürün listeleme, sipariş oluşturma ve kullanıcı girişi REST ile yapılabilir. Yönetim panelinde kullanıcı, stok, sipariş ve rapor özetleri GraphQL ile tek sorguda çekilebilir. Kritik stok değişiklikleri veya canlı sipariş bildirimleri ise WebSocket ile anlık gösterilebilir.

REST:
GET /urunler
POST /siparisler
PUT /kullanicilar/7

GraphQL:
query {
  dashboard {
    toplamSiparis
    kritikStoklar {
      urunAdi
      kalanAdet
    }
    sonHareketler {
      tarih
      aciklama
    }
  }
}

WebSocket:
Yeni sipariş geldiğinde panel ekranına anlık bildirim gönder.

API Cevapları Genelde JSON Döner

Modern web API’lerinde veri çoğunlukla JSON formatında taşınır. JSON hem insan tarafından okunabilir hem de JavaScript, PHP, Python, Java, C# gibi dillerde kolayca işlenebilir.

{
  "id": 15,
  "baslik": "API Nedir?",
  "kategori": "Web Geliştirme",
  "yazar": {
    "ad": "Editör",
    "rol": "Teknik İçerik"
  },
  "etiketler": ["API", "REST", "GraphQL", "WebSocket"]
}

Frontend tarafı bu JSON verisini alır ve ekranda istediği tasarıma dönüştürür. API burada veri taşıma görevini üstlenir; tasarım ve kullanıcı deneyimi ise istemci tarafında şekillenir.

API Güvenliği: Anahtar, Token ve Yetki Kontrolü

API sadece veri taşımakla ilgili değildir; aynı zamanda güvenlik konusudur. Her endpoint herkese açık olmamalıdır. Bazı API’ler public olabilir; örneğin genel haber listesi veya herkese açık hava durumu verisi. Ama sipariş oluşturma, kullanıcı bilgisi, stok hareketi veya ödeme işlemi gibi alanlarda mutlaka kimlik doğrulama ve yetki kontrolü gerekir.

API güvenliğinde sık kullanılan kavramlar şunlardır: API key, access token, OAuth, JWT, rate limit, CORS, role-based authorization ve audit log. Yeni başlayan biri için ilk aşamada şunu bilmek yeterlidir: API’ye gelen her isteğin kimden geldiği, ne yapmaya yetkili olduğu ve kötüye kullanım ihtimali kontrol edilmelidir.

API Tasarlarken Dikkat Edilmesi Gerekenler

İyi API sadece çalışan API değildir. Anlaşılır, tutarlı, güvenli, belgelenmiş ve sürdürülebilir API iyi API’dir. Bir API’yi sadece bugünkü ekran için değil, ileride mobil uygulama, raporlama servisi, entegrasyon veya otomasyon aracı tarafından da kullanılabilecek şekilde düşünmek gerekir.

Yeni Başlayan Biri Hangisini Öğrenmeli?

Net cevap: önce REST öğrenmek en mantıklı başlangıçtır. Çünkü REST, web API dünyasının temel dilidir. HTTP metotlarını, endpoint mantığını, JSON cevaplarını, status kodlarını ve istemci-sunucu ilişkisini anlamadan GraphQL veya WebSocket’e geçmek konuyu gereksiz zorlaştırabilir.

REST’i anladıktan sonra GraphQL öğrenmek çok daha kolay olur. Çünkü GraphQL’in hangi problemi çözdüğünü daha iyi fark edersin: fazla veri, eksik veri ve karmaşık ekranlar. WebSocket ise gerçek zamanlı uygulama ihtiyacı doğduğunda öğrenilmelidir. Mesajlaşma, canlı fiyat, bildirim veya takip ekranı yapmıyorsan ilk gün WebSocket’e dalmak şart değildir.

Kısa Karar Rehberi

API yaklaşımı seçerken aşağıdaki sorular pratik karar vermeyi kolaylaştırır.

Faydalı Resmi Kaynaklar