API Tasarımı ve Mikroservis Mimarisi: Ölçeklenebilir Sistemler İnşa Etmek

Modern yazılım geliştirmede API’ler, uygulamaların birbirleriyle konuşmasını sağlayan evrensel dildir. IPEC Labs olarak NŞEFİM restoran yönetim platformunda günde binlerce API çağrısını işleyen, gerçek zamanlı WebSocket bağlantılarını yöneten ve dört farklı yemek platformuyla entegre çalışan bir API altyapısı geliştirdik. Bu yazıda, production ortamında kanıtlanmış API tasarım prensiplerini ve mikroservis mimarisi deneyimlerimizi paylaşıyoruz.

RESTful API Tasarımının Altın Kuralları

İyi bir API tasarımı, geliştirici deneyimini (DX) merkeze alır. API’nizi kullanan geliştiriciler, ister ekibinizden biri olsun, ister üçüncü taraf bir entegratör, dokümantasyona minimum düzeyde başvurarak çalışabilmelidir.

İlk ve en önemli kural tutarlılıktır. URL yapısı, HTTP method kullanımı, hata formatı ve pagination yaklaşımı API genelinde tutarlı olmalıdır. NŞEFİM API’mizde tüm endpoint’ler aynı kalıpları takip eder. Koleksiyon endpoint’leri çoğul isim kullanır (orders, products, branches), tekil kaynak erişimi ID ile yapılır, filtreleme query parameter’ları ile gerçekleşir.

İkinci kural doğru HTTP method kullanımıdır. GET sadece veri okuma için, POST yeni kayıt oluşturmak için, PUT/PATCH mevcut kaydı güncellemek için, DELETE silmek için kullanılır. NŞEFİM’de sipariş durumu güncellemesi PATCH ile yapılır, çünkü siparişin tamamını değil, sadece status alanını güncelliyoruz.

Üçüncü kural anlamlı HTTP status kodlarıdır. 200 başarılı okuma, 201 başarılı oluşturma, 400 geçersiz istek, 401 kimlik doğrulama hatası, 403 yetki hatası, 404 kaynak bulunamadı, 429 rate limit aşımı, 500 sunucu hatası. Her status kodu, istemcinin hatayı programatik olarak ele almasına olanak tanır.

Mikroservis Mimarisi: Ne Zaman ve Neden?

Monolitik mimari basit ve hızlı başlamak için idealdir. Ancak uygulama büyüdükçe, ekip genişledikçe ve farklı bileşenlerin farklı ölçekleme ihtiyaçları ortaya çıktıkça mikroservisler kaçınılmaz hale gelir.

NŞEFİM platformu başlangıçta monolitik bir yapıdaydı. Ancak sipariş hacmi arttıkça ve platform entegrasyonları çoğaldıkça mikroservis mimarisine geçiş zorunlu hale geldi. Bugün NŞEFİM beş ana servisten oluşmaktadır.

Birincisi API Gateway servisidir, tüm isteklerin giriş noktası, kimlik doğrulama, rate limiting ve routing’den sorumludur. İkincisi Order Service, sipariş oluşturma, güncelleme ve takip işlemlerini yönetir. Üçüncüsü Kitchen Display Service, mutfak ekranlarına gerçek zamanlı sipariş iletimi ve hazırlık durumu takibi sağlar. Dördüncüsü Integration Service, Yemeksepeti, Getir, Trendyol ve Migros API’leriyle iletişimi yönetir. Beşincisi Finance Service, gelir-gider takibi, kasa raporları ve konsolide finans hesaplamalarını gerçekleştirir.

Her servis bağımsız olarak deploy edilebilir, ölçeklendirilebilir ve güncellenebilir. Yemek saatlerinde sipariş servisi otomatik olarak ölçeklenirken, finans servisi sabit kapasitede çalışmaya devam eder.

WebSocket: Gerçek Zamanlı İletişimin Kalbi

NŞEFİM’in en kritik özelliklerinden biri, siparişlerin anlık olarak mutfak ekranına düşmesidir. Bu, HTTP’nin istek-yanıt modeliyle mümkün değildir, WebSocket ile sürekli açık bir bağlantı üzerinden çift yönlü iletişim gerekir.

WebSocket bağlantı yönetimi production ortamında ciddi zorluklar sunar. Bağlantı kopmaları kaçınılmazdır, ağ kesintileri, sunucu yeniden başlatmaları veya istemci tarafındaki sorunlar bağlantıyı koparabilir. Bu nedenle otomatik yeniden bağlanma mekanizması (exponential backoff ile) kritik önem taşır. NŞEFİM’de bağlantı koptuğunda istemci 1 saniye, ardından 2 saniye, 4 saniye artan aralıklarla yeniden bağlanmayı dener. Maksimum 30 saniyeye ulaşıldığında aralık sabitlenir.

Heartbeat mekanizması bağlantının canlılığını doğrulamak için kullanılır. Her 30 saniyede bir sunucu “ping” gönderir, istemci “pong” ile yanıt verir. 90 saniye boyunca pong alınmazsa bağlantı kopuk kabul edilir ve kaynaklar serbest bırakılır.

Mesaj sıralama ve teslimat garantisi de önemlidir. Siparişlerin doğru sırada ve eksiksiz olarak mutfak ekranına ulaşması hayati önem taşır. Her mesaja sequence number atanır ve istemci eksik mesajları tespit ederek sunucudan tekrar talep edebilir.

API Güvenliği

API güvenliği, IPEC Labs’ın öncelikli odak alanlarından biridir. Güvenlik stratejimiz çok katmanlıdır.

JWT (JSON Web Token) tabanlı kimlik doğrulama kullanıyoruz. Access token’lar kısa ömürlüdür (15 dakika), refresh token’lar daha uzundur (7 gün). Token’lar HttpOnly cookie’lerde saklanır, JavaScript ile erişilemez, XSS saldırılarına karşı korumalı.

Rate limiting ile kötüye kullanımı önlüyoruz. Her API endpoint’i için dakikada maksimum istek sayısı belirlenmiştir. NŞEFİM’de login endpoint’i dakikada 10 istek ile sınırlıdır, brute force saldırılarını etkili bir şekilde engeller. Sipariş listeleme endpoint’i ise dakikada 100 istekle sınırlıdır.

Input validation, her gelen verinin güvenli olduğundan emin olmanın ilk hattıdır. SQL injection, XSS ve diğer injection saldırılarına karşı tüm girdiler sanitize edilir. Zod kütüphanesi ile TypeScript seviyesinde runtime validation uygulanır.

CORS politikaları, sadece yetkili domain’lerden gelen isteklerin kabul edilmesini sağlar. NŞEFİM API’si sadece nsefim.com ve app.nsefim.com domain’lerinden gelen istekleri kabul eder.

Platform Entegrasyonları: Gerçek Dünya Zorlukları

NŞEFİM’in Yemeksepeti, Getir, Trendyol ve Migros entegrasyonları, API tasarımının gerçek dünya zorluklarını gösteren mükemmel bir case study’dir.

Her platform farklı API standartları kullanır. Biri REST kullanırken diğeri webhook tabanlıdır. Veri formatları farklıdır, biri JSON, diğeri XML gönderebilir. Hata kodları standardize değildir. Rate limit politikaları farklıdır.

Bu karmaşıklığı yönetmek için Adapter Pattern kullandık. Her platform için ayrı bir adapter modülü yazıldı. Adapter, platform spesifik veriyi NŞEFİM’in standart veri modeline dönüştürür. Ana iş mantığı platform detaylarından tamamen habersizdir, sadece standart sipariş objesiyle çalışır.

Circuit Breaker pattern’ı ile platform arızalarına dayanıklılık sağladık. Bir platform API’si yanıt vermiyorsa, circuit breaker devreye girer ve belirli bir süre o platforma istek göndermez. Bu, cascade failure’ları (zincirleme arızaları) önler ve sistemin geri kalanının sağlıklı çalışmaya devam etmesini sağlar.

Veritabanı Erişim Katmanı

API ve veritabanı arasındaki katman, performans ve güvenlik açısından kritiktir. IPEC Labs’ta ORM (Object-Relational Mapping) olarak Prisma kullanıyoruz.

Prisma’nın tip güvenliği, TypeScript ile birleştiğinde veritabanı sorgularında derleme zamanı hata tespiti sağlar. Yanlış tablo adı veya sütun adı kullanırsanız, uygulama derlenmez bile. Bu, runtime hatalarını dramatik şekilde azaltır.

N+1 sorgu problemi, ORM kullanımının en yaygın performans tuzaklarından biridir. NŞEFİM’de sipariş listesini çekerken her siparişin ürünlerini ayrı ayrı sorgulamak yerine, Prisma’nın include özelliği ile tek sorguda tüm ilişkili verileri çekiyoruz.

Connection pooling, veritabanı bağlantılarının verimli kullanımını sağlar. Her istek için yeni bağlantı açmak yerine, bir bağlantı havuzundan mevcut bağlantılar kullanılır ve işlem bittiğinde havuza geri döner.

Dokümantasyon ve Geliştirici Deneyimi

En iyi API, en iyi dokümante edilmiş API’dir. NŞEFİM API’si OpenAPI 3.0 spesifikasyonu ile dokümante edilmiştir. Swagger UI ile interaktif dokümantasyon sunulmaktadır, geliştiriciler tarayıcıdan doğrudan API çağrıları yapabilir.

Her endpoint için istek ve yanıt örnekleri, hata senaryoları ve rate limit bilgileri dokümante edilmiştir. Postman koleksiyonu olarak export edilebilir, otomatik SDK üretimi için kullanılabilir.

Sonuç

API tasarımı ve mikroservis mimarisi, modern yazılım mühendisliğinin temel taşlarıdır. Doğru tasarlanmış bir API, uygulamanızın ömrünü uzatır, ekibinizin verimliliğini artırır ve entegrasyon maliyetlerini düşürür.

IPEC Labs olarak NŞEFİM’den NZeca’ya, Akıllı Okul’dan kurumsal projelere kadar tüm ürünlerimizde bu prensipleri uyguluyoruz. API’lerimiz, müşterilerimizin ve partnerlerimizin güvenle entegre olabileceği sağlam temeller sunmaktadır.