API Entegrasyon Modelleri: Kurumsal Mimari İçin En İyi Uygulamalar

Modern işletmeler entegrasyonlarla çalışır. Ortalama orta ölçekli bir şirket 110'dan fazla yazılım uygulaması kullanıyor ve her birinin değer sağlamak için diğerleriyle veri alışverişinde bulunması gerekiyor. E-ticaret platformunuzun ERP'nizle konuşması gerekiyor. ERP'nizin depo yönetim sisteminizle konuşması gerekir. Pazarlama otomasyonunuz, CRM'nizden müşteri verilerine ihtiyaç duyar. Muhasebe sisteminiz, ödeme işlemcinizden gelen işlem verilerine ihtiyaç duyar. Her bağlantı bir entegrasyondur ve her entegrasyon bir API görüşmesidir.

Sorunsuz bir şekilde ölçeklenen bir işletme ile entegrasyon borcunda boğulan bir işletme arasındaki fark, mimari kalıplara bağlıdır. İyi tasarlanmış entegrasyon modellerini uygulayan şirketler, tutarlı bir strateji olmadan noktadan noktaya bağlantılar kuran şirketlere kıyasla entegrasyonları sürdürmek için %60 daha az zaman harcıyor ve entegrasyonla ilgili kesintilerle %80 daha az karşılaşıyor.

Önemli Çıkarımlar

• REST, harici entegrasyonlar için baskın API stili olmayı sürdürüyor ancak GraphQL ve gRPC'nin her biri belirli kullanım durumlarına daha iyi hizmet ediyor
• Olay odaklı mimari (web kancaları, mesaj kuyrukları) sistemleri birbirinden ayırır ve yoklamayı ortadan kaldırır, entegrasyon gecikmesini dakikalardan saniyelere indirir
• Destan modeli, dağıtılmış kilitler olmadan birden fazla hizmetteki dağıtılmış işlemleri yönetir; ERP, ödeme ve depo sistemlerini kapsayan sipariş karşılama gibi operasyonlar için gereklidir
• API ağ geçitleri, kesişen konuları (kimlik doğrulama, hız sınırlama, izleme) merkezileştirir ve entegrasyon başına ek yükü %40-60 oranında azaltır
• Hız sınırlaması sadece kibarlık değildir; hem sistemlerinizi hem de entegre olduğunuz sistemleri art arda gelen arızalardan korur
• API versiyonlama stratejisine, konuşmayı zorlayan son değişikliklerden sonra değil, ilk tüketicinizden önce karar verilmelidir.
• Entegrasyon katmanı çoğu kurumsal mimarinin en kırılgan parçasıdır; izlemeye, hata işlemeye yatırım yapın ve mantığı ilk günden itibaren yeniden deneyin

---

REST doğru seçim olduğunda:

• Harici geliştiriciler tarafından kullanılan genel API'ler
• Ticari kuruluşlarda standart CRUD işlemleri
• Basitliğin ve geniş takım desteğinin önemli olduğu entegrasyonlar
• Birçok farklı istemci (web, mobil, iş ortakları) tarafından tüketilecek API'ler

Kurumsal REST'in en iyi uygulamaları:

1. Kaynaklar için isimler, eylemler için HTTP yöntemleri kullanın: GET /orders/123, GET /getOrder?id=123 değil
2. Tutarlı yanıt formatı: Her zaman aynı zarf yapısını döndürün ({ data, meta, errors })
3. Koleksiyonlar için sayfalandırma: Büyük veri kümeleri için yüksek uzaklıklarda yavaşlayan ofset tabanlı (?page=5&per_page=50) değil, imleç tabanlı sayfalama (?cursor=abc123&limit=50) kullanın
4. Keşfedilebilirlik için HATEOAS: Yanıtlara ilgili kaynaklara bağlantılar ekleyin ({ "order": { ..., "links": { "customer": "/customers/456", "invoices": "/orders/123/invoices" }}})
5. Tutarlı hata formatı: Makine tarafından okunabilen kodlar, insanlar tarafından okunabilen mesajlar ve belge bağlantılarıyla yapılandırılmış hataları döndürün

GraphQL

GraphQL, müşterilerin tam olarak ihtiyaç duydukları verileri tek bir sorguda talep etmelerine olanak tanıyarak REST'in aşırı ve az getirme sorunlarını ortadan kaldırır. Müşteri yanıt şeklini tanımlar.

GraphQL doğru seçim olduğunda:

• Bant genişliğinin kısıtlı olduğu mobil uygulamalar
• Tek bir istekte birden fazla ilgili varlıktan esnek verilere ihtiyaç duyan ön uç uygulamaları
• Farklı tüketicilerin aynı verilerin farklı alt kümelerine ihtiyaç duyduğu API'ler
• API sözleşmesinin kullanıcı arayüzünü kısıtlamaması gereken hızlı ön uç geliştirme

GraphQL yanlış seçim olduğunda:

• Tahmin edilebilir erişim modellerine sahip basit CRUD API'leri
• Yanıt şeklinin sabit olduğu sunucudan sunucuya entegrasyonlar
• Agresif önbelleğe alma gerektiren API'ler (REST'in URL tabanlı önbelleğe alma işlemi daha basittir)
• GraphQL uzmanlığı olmayan ekipler (öğrenme eğrisi REST'ten daha diktir)

GraphQL kurumsal hususları:

• Yetkilendirme karmaşıklığı: Alan düzeyinde yetkilendirme gereklidir — şema onu açığa çıkardığı için müşteri user { creditCardNumber } sorgulayamamalıdır
• Sorgu maliyet analizi: Derinlik ve karmaşıklık sınırları olmaksızın, tek bir GraphQL sorgusu çok büyük sunucu kaynaklarını tüketebilir. Sorgu maliyet tahminini uygulayın ve pahalı sorguları reddedin
• N+1 sorun: Deneyimsiz GraphQL çözümleyicileri, alan ve öğe başına bir veritabanı sorgusu oluşturur. Toplu işlem için DataLoader modelini kullanın
• Önbellekleme: GraphQL'in tek uç noktası, HTTP önbelleğe almayı etkisiz hale getirir. Uygulama düzeyinde önbelleğe almayı (Redis) veya kalıcı sorguları kullanın

gRPC

gRPC, şema tanımı ve ikili serileştirme için Protokol Arabelleklerini, aktarım için ise HTTP/2'yi kullanır. Yüksek hacimli, düşük gecikmeli iletişimler için REST'ten önemli ölçüde daha hızlıdır.

gRPC doğru seçim olduğunda:

• Mikro hizmet mimarilerinde dahili hizmetten hizmete iletişim
• Yüksek verimli, düşük gecikmeli gereksinimler (10.000'den fazla istek/saniye)
• Veri akışı (gerçek zamanlı güncellemeler için çift yönlü akış)
• Hizmetlerin farklı dillerde yazıldığı çok dilli ortamlar (gRPC, tek bir .proto tanımından 10'dan fazla dil için istemci kodu oluşturur)

gRPC uygun olmadığında:

• Genel API'ler (tarayıcı desteği sınırlıdır, araçlara daha az erişilebilir)
• REST'in basitliğinin gRPC'nin performansından daha ağır bastığı basit entegrasyonlar
• Standart HTTP araçlarıyla (curl, Postman) hata ayıklamanın önemli olduğu ortamlar

Karşılaştırma Özeti

---

Olay Odaklı Mimari

İstek-yanıt API'leri (REST, GraphQL, gRPC), tüketicinin bilgi istemesini gerektirir. Olay odaklı mimari bunu tersine çevirir; üreticiler durum değişiklikleri meydana geldiğinde olayları yayınlar ve ilgilenen tüketiciler bu olaylara tepki verir. Bu temel değişim yoklamayı ortadan kaldırır, birleştirmeyi azaltır ve sistemler arasında gerçek zamanlı veri akışını mümkün kılar.

Web kancaları

Web kancaları olaya dayalı entegrasyonun en basit biçimidir. Sistem A'da bir olay meydana geldiğinde, Sistem B tarafından kaydedilen bir URL'ye bir HTTP POST isteğinde bulunulur.

Yaygın e-ticaret web kancası senaryoları:

• Stripe, sipariş yönetimi hizmetinize payment_intent.succeeded gönderir
• Shopify, siparişin yerine getirilmesi için ERP'nize orders/create gönderir
• Odoo depo yönetim sisteminize stock.move/confirmed gönderir
• CRM'niz fatura oluşturma için muhasebe sisteminize deal.won gönderir

Webhook'un en iyi uygulamaları:

1. Web kancası imzalarını doğrulayın: Her web kancası sağlayıcısı bir imza başlığı (HMAC-SHA256 karma) içerir. Sahte web kancalarını önlemek için işlemeden önce doğrulayın
2. Hızlı yanıt verin, daha sonra işleyin: Hemen 200'ü döndürün, ardından webhook yükünü eşzamansız olarak işleyin. Uzun süren işleme zaman aşımı riskine neden olur ve gönderen yeniden deneyecektir (kopyalara neden olur)
3. Idempotency: Web kancaları birden çok kez teslim edilebilir (sağlayıcı, ağ arızasında yeniden deneme yapar). İşleyicilerinizi bağımsız olacak şekilde tasarlayın; aynı web kancasını iki kez işlemek, yinelenen kayıtlar oluşturmamalıdır
4. İşlemeyi yeniden dene: Gelen web kancalarını işlenme durumlarıyla birlikte saklayın. İşleme başarısız olursa sağlayıcının yeniden deneme planına bağlı kalmak yerine kendi yeniden deneme mekanizmanızı uygulayın
5. Ölü mektup kuyruğu: Maksimum yeniden deneme sayısından sonra, başarısız olan web kancalarını sessizce bırakmak yerine manuel inceleme için geçersiz ileti kuyruğuna taşıyın

Mesaj Kuyrukları

Garantili teslimat gerektiren yüksek hacimli olay akışları ve senaryolar için mesaj kuyrukları (RabbitMQ, Apache Kafka, AWS SQS/SNS, Google Pub/Sub) güçlü olay dağıtımı sağlar.

Web kancaları üzerinden mesaj kuyrukları ne zaman kullanılmalı:

• Dahili hizmetten hizmete iletişim (web kancaları harici sağlayıcı entegrasyonu için daha iyidir)
• Yüksek olay hacmi (1.000+ olay/dakika)
• Yapılandırılabilir yeniden deneme politikalarıyla garantili teslimat ihtiyacı
• Bir olayın birden fazla tüketicideki eylemleri tetiklediği yayılma senaryoları
• Olayı tekrar oynatma yeteneği (Kafka olayları korur ve tüketicilerin herhangi bir noktadan tekrar oynatmasına olanak tanır)

Mesaj kuyruğu kalıpları:

Noktadan noktaya (Kuyruk): Tek üretici, tek tüketici. Her olayı tam olarak bir hizmetin işlemesi gerektiğinde kullanılır. Örnek: Sipariş oluşturuldu → Karşılama hizmeti süreçleri (sipariş başına yalnızca bir karşılama eylemi).

Yayınla-Abone Ol (Konu): Bir üretici, birden fazla tüketici. Her tüketici her etkinliğin bir kopyasını alır. Yayılma senaryoları için kullanılır. Örnek: Sipariş oluşturuldu → Envanter hizmeti stoğu ayırır VE E-posta hizmeti onay gönderir VE Analytics hizmeti olayı kaydeder.

Örnek mimari: Sipariş karşılama

┌──────────┐     order.created      ┌──────────────┐
│ Commerce │ ──────────────────────► │ Message Bus  │
│ Service  │                        │ (Kafka/SQS)  │
└──────────┘                        └──────┬───────┘
                                           │
                    ┌──────────────────────┬┴──────────────────┐
                    │                      │                    │
              ┌─────▼──────┐      ┌───────▼──────┐    ┌──────▼───────┐
              │ Inventory  │      │   Payment    │    │    Email     │
              │  Service   │      │   Service    │    │   Service    │
              │ (reserve)  │      │  (capture)   │    │(confirmation)│
              └────────────┘      └──────────────┘    └──────────────┘

Etkinlik Şeması Tasarımı

Kuruluşunuz genelinde tutarlı olay şemaları entegrasyon sorunlarını azaltır:

{
  "event_id": "evt_abc123xyz",
  "event_type": "order.created",
  "timestamp": "2026-03-23T14:30:00Z",
  "version": "2.0",
  "source": "commerce-service",
  "data": {
    "order_id": "ORD-2026-00142",
    "customer_id": "CUST-789",
    "total_amount": 249.99,
    "currency": "USD",
    "line_items": [...]
  },
  "metadata": {
    "correlation_id": "req_xyz789",
    "trace_id": "trace_abc456"
  }
}

Anahtar unsurlar:

• event_id: Yeterlilik kontrolü için benzersiz tanımlayıcı
• event_type: {entity}.{action} kuralını izleyen nokta işaretli tür
• sürüm: Geriye dönük uyumluluk için şema sürümü
• kaynak: Hizmet tanımlayıcısı üretiliyor
• correlation_id: Hata ayıklama için ilgili olayları hizmetler arasında bağlar

---

Dağıtılmış İşlemler için Efsanevi Model

Monolitik uygulamalarda, birden çok adıma yayılan iş operasyonları (sipariş oluşturma, envanter ayırma, ödemeyi tahsil etme, sevkiyat oluşturma) tek bir veritabanı işleminde yürütülür; herhangi bir adım başarısız olursa tüm işlem atomik olarak geri alınır.

Her adımın kendi veritabanına sahip farklı bir hizmeti içerdiği dağıtık sistemlerde geleneksel işlemler çalışmaz. Destan modeli, işlemi geri alma işlemlerini telafi eden yerel işlemler dizisine bölerek bir alternatif sağlar.

Koreografi Efsanesi

Her hizmet olayları dinler ve bundan sonra ne yapılacağına karar verir. Merkezi bir koordinatör bulunmamaktadır.

Örnek: Siparişin yerine getirilmesi destanı (koreografi)

1. Ticaret Hizmeti sipariş oluşturur → order.created yayınlar
2. Envanter Hizmeti order.created duyar → stok ayırır → stock.reserved yayınlar
3. Ödeme Hizmeti stock.reserved ifadesini duyar → ödemeyi kaydeder → payment.captured öğesini yayınlar
4. Karşılama Hizmeti payment.captured ifadesini duyar → gönderiyi oluşturur → shipment.created öğesini yayınlar

Ödeme başarısız olursa: 3. Ödeme Hizmeti stock.reserved ifadesini duyar → ödeme başarısız olur → payment.failed öğesini yayınlar 4. Envanter Hizmeti payment.failed ifadesini duyar → ayrılmış stoğu serbest bırakır (telafi edici işlem) 5. Ticaret Hizmeti payment.failed ifadesini duyar → siparişi başarısız olarak işaretler → müşteriye bildirir

Avantajları: Basittir, tek bir hata noktası yoktur, olay odaklı sistemlere doğal uyum sağlar. Dezavantajları: Genel destan durumunu takip etmek zordur; hata ayıklama, hizmetler arasındaki olayların ilişkilendirilmesini gerektirir; yeni adımlar eklemek, mevcut hizmetlerin değiştirilmesini gerektirir.

Orkestrasyon Efsanesi

Merkezi bir orkestratör hizmeti, destan adımlarını koordine eder, her hizmete komutlar gönderir ve yanıtları yönetir.

Örnek: Sipariş gerçekleştirme efsanesi (düzenleme)

┌──────────────────────────────┐
│    Order Orchestrator         │
│                              │
│  1. Reserve inventory ───────┼──► Inventory Service
│     ◄── stock.reserved ──────┤
│                              │
│  2. Capture payment ─────────┼──► Payment Service
│     ◄── payment.captured ────┤
│                              │
│  3. Create shipment ─────────┼──► Fulfillment Service
│     ◄── shipment.created ────┤
│                              │
│  On any failure:             │
│  - Compensate previous steps │
│  - Update order status       │
│  - Notify customer           │
└──────────────────────────────┘

Avantajları: Efsane durumuna ilişkin net görünürlük, daha kolay hata ayıklama, yeni adımların eklenmesi yalnızca orkestratörün değiştirilmesini gerektirir. Dezavantajları: Tek hata noktası (yedeklik ile azaltılır), orkestratör bir darboğaz haline gelebilir ve ilk uygulama daha karmaşık hale gelebilir.

Öneri: Karmaşık destanlar için orkestrasyon (5+ adım, birden fazla koşullu yol) ve basit destanlar için koreografi (2-3 adım, doğrusal akış) kullanın.

---

API Ağ Geçidi Mimarisi

Bir API ağ geçidi, API tüketicileri ile arka uç hizmetleri arasında yer alır ve her API'nin ihtiyaç duyduğu ancak her hizmette tekrarlanmaması gereken, birbiriyle kesişen endişeleri ele alır.

Ağ Geçidi Sorumlulukları

Kimlik doğrulama ve yetkilendirme: JWT belirteçlerini, API anahtarlarını veya OAuth belirteçlerini her arka uç hizmeti yerine ağ geçidinde bir kez doğrulayın. Ağ geçidi, iletilen isteklere doğrulanmış kimlik bilgilerini ekler.

Hız sınırlama: Tüketici başına hız sınırları uygulayarak arka uç hizmetlerini aşırı yükten koruyun. Farklı tüketiciler (dahili hizmetler, iş ortakları, kamu geliştiricileri) farklı ücret limitlerine sahiptir.

Yönlendirme isteği: Gelen istekleri, URL yoluna, üstbilgilere veya istek içeriğine göre uygun arka uç hizmetine yönlendirin. Bu, genel API yapısını dahili hizmet mimarisinden ayırır.

Yanıt önbelleğe alma: Sıkça talep edilen, yavaş değişen veriler (ürün katalogları, yapılandırma) için yanıtları önbelleğe alın. Arka uç yükünü azaltır ve yanıt süresini artırır.

İstek/yanıt dönüşümü: Genel API biçimleri ile dahili hizmet biçimleri arasında çeviri yapın. Genel API, dahili hizmet API'leri değişse bile sabit kalabilir.

İzleme ve günlüğe kaydetme: Hata ayıklama, analiz ve uyumluluk için tüm API trafiğinin merkezi olarak günlüğe kaydedilmesi.

Ağ Geçidi Seçenekleri

Ön Uç (BFF) Modeli için Arka Uç

Her ön uç uygulamasının (web, mobil, iş ortağı portalı) kendi özel ağ geçidi hizmetini aldığı özel bir API ağ geçidi biçimi. BFF, birden fazla arka uç hizmetine yapılan çağrıları toplar ve tam olarak ön ucun ihtiyaç duyduğu verileri döndürür.

Neden tek bir ağ geçidi üzerinden BFF:

• Mobil, web'den farklı yanıt şekillerine ihtiyaç duyar (daha küçük yükler, farklı alan kümeleri)
• İş ortağı portalı, müşteriye yönelik web'den farklı yetkilendirme kurallarına ihtiyaç duyar
• Her ön uç ekibi BFF'lerini bağımsız olarak geliştirebilir

Bu, ECOSIRE'ın başsız ERP uygulamaları için kullandığı kalıptır — Odoo API çağrılarını toplayan ve her sayfa bileşeninin ihtiyaç duyduğu verileri tam olarak içeren bir Next.js ön ucu sunan bir NestJS BFF katmanıdır.

---

Hız Sınırlama Stratejileri

Hız sınırlaması hem bir güvenlik mekanizması hem de bir güvenilirlik mekanizmasıdır. Bu olmadan, hatalı çalışan tek bir entegrasyon API'nizi zorlayabilir ve tüm tüketiciler için kesintiye neden olabilir.

Hız Sınırlama Algoritmaları

Sabit pencere: İstekleri sabit zaman pencerelerinde sayın (ör. dakikada 100 istek). Basittir ancak pencere sınırlarında patlamalara izin verir (bir pencere sınırına yayılan 2 saniyede 200 istek).

Kayan pencere: Geçerli ve önceki pencere sayılarının ağırlıklı ortalaması. Sabit pencereye göre daha sorunsuz oran uygulaması.

Jeton kümesi: Jetonlar sabit bir oranda birikir (ör. 10 jeton/saniye). Her istek bir jeton tüketir. Ortalama hızı zorlarken kontrollü patlamalara (kova kapasitesine kadar) izin verir. En yaygın uygulama.

Sızdıran paket: İstekler, sabit bir hızda işlenen bir kuyruğa girer. Fazla talepler reddedilir. En yumuşak çıktı hızını sağlar ancak gecikmeyi artırır.

Hız Sınırı Yapılandırması

Hız Sınırı Yanıt Başlıkları

Tüketicilerin kendi kendine kısma yapabilmesi için yanıt başlıklarına hız sınırı bilgisini ekleyin:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1711209600
Retry-After: 30

Hız sınırlı olduğunda, tüketicinin ne zaman yeniden deneyebileceğini belirten Retry-After başlığıyla HTTP 429'u (Çok Fazla İstek) döndürün.

---

API Sürümü Oluşturma

API'ler gelişiyor. Yeni alanlar eklenir, davranışlar değişir ve bazen değişikliklerden kaçınılamaz. Sürüm oluşturma stratejiniz, bu değişikliklerin tüketicilere ne kadar zarif bir şekilde iletileceğini belirler.

Sürüm Oluşturma Stratejileri

URL yolu sürüm oluşturma (/v1/orders, /v2/orders): En açık, tüketicilerin anlaması ve uygulaması en kolay olanıdır. Çoğu API için önerilen yaklaşım.

Başlık sürümü oluşturma (Accept: application/vnd.company.v2+json): Daha temiz URL'ler ancak daha az keşfedilebilir. Tarayıcıda veya basit araçlarla test etmek daha zordur.

Sorgu parametresi sürümü oluşturma (/orders?version=2): Uygulaması kolaydır ancak sorgu dizesini kirletir ve önbelleğe almayla çakışır.

Kesintili ve Kesintisiz Değişiklikler

Kırılmaz (geriye dönük uyumlu):

• Yanıtlara yeni isteğe bağlı alanlar ekleme
• İsteklere yeni isteğe bağlı parametreler ekleme
• Yeni uç noktalar ekleme
• Yeni numaralandırma değerleri ekleme (tüketiciler bilinmeyen değerleri incelikle ele alıyorsa)

Kırılma:

• Alanları kaldırma veya yeniden adlandırma
• Alan türlerini değiştirme
• Mevcut alanların anlamını değiştirme
• İsteğe bağlı parametrelerin gerekli hale getirilmesi
• URL yollarını veya HTTP yöntemlerini değiştirme
• Kimlik doğrulama gereksinimlerinin değiştirilmesi

En İyi Sürüm Oluşturma Uygulamaları

1. Versiyon oluşturmaya ilk günden başlayın: Sürüm oluşturmayı daha sonra eklemek, mevcut tüketiciler için zahmetlidir
2. En fazla 2 aktif sürümün bakımını yapın: Her ek sürüm, bakım yükünü artırır
3. Kullanımdan kaldırılma zaman çizelgesi: Bir sürümün kaldırılmasından 6+ ay önce kullanımdan kaldırıldığını duyurun. Kullanımdan kaldırma bildirimlerini yanıt başlıklarına ekleyin (Sunset: 2027-01-01)
4. Sözleşmenin sürümü, uygulamanın değil: Tüm sürümler, yanıt dönüşüm katmanlarıyla aynı arka uç kodunu paylaşabilir
5. Belge taşıma kılavuzları: Her sürüm artışı için nelerin değiştiğini ve nasıl güncelleneceğini açıklayan ayrıntılı bir kılavuz sağlayın

---

Hata İşleme ve Yeniden Deneme Modelleri

Yapılandırılmış Hata Yanıtları

Her API hata yanıtı şunları içermelidir:

{
  "error": {
    "code": "INSUFFICIENT_INVENTORY",
    "message": "Requested quantity (10) exceeds available stock (3) for product SKU-12345",
    "status": 422,
    "details": {
      "product_id": "SKU-12345",
      "requested": 10,
      "available": 3
    },
    "documentation_url": "https://api.example.com/docs/errors#INSUFFICIENT_INVENTORY",
    "request_id": "req_abc123"
  }
}

Üstel Geri Alma ile Yeniden Deneyin

Geçici arızalar için (ağ hataları, 503 Hizmet Kullanılamıyor, 429 Çok Fazla İstek), üstel geri çekilme ve titreşimle yeniden denemeyi uygulayın:

Yeniden deneme aralıkları: 1 sn, 2 sn, 4 sn, 8 sn, 16 sn (üstel) + gürleyen sürüyü önlemek için rastgele titreşim (0-1 sn)

Maksimum yeniden deneme sayısı: API çağrıları için 5 deneme, webhook teslimatları için 10 deneme

Devre kesici: Ardışık arızalar bir eşiği aştığında (örneğin, 1 dakikada 5 arıza), yeniden denemeyi bırakın ve tekrar denemeden önce 30 saniye boyunca hızlı başarısız olun. Bu, zaten zor durumda olan bir hizmetin bunaltılmasını önler.

Geçersiz Mektup Kuyrukları

Maksimum yeniden deneme sayısı tükendikten sonra, başarısız istekleri sessizce bırakmak yerine, geçersiz iletiler kuyruğuna taşıyın. Teslim edilmeyen mektup kuyrukları şunları sağlar:

• Kalıcı arızaların manuel olarak araştırılması
• Temel sorun çözüldükten sonra toplu tekrar oynatma
• Teslim edilmeyen mektup kuyruğu derinliği hakkında uyarı (entegrasyon sorunlarının erken uyarısı)

---

Sıkça Sorulan Sorular

API'm için REST mi yoksa GraphQL mi kullanmalıyım?

Yanıt şekillerinin öngörülebilir olduğu genel API'ler, basit CRUD işlemleri ve sunucudan sunucuya entegrasyonlar için REST'i kullanın. Aynı API'den farklı veri alt kümelerine ihtiyaç duyan birden fazla ön uç tüketiciniz olduğunda veya HTTP gidiş dönüşlerini azaltmanın kritik olduğu durumlarda (mobil uygulamalar) GraphQL'i kullanın. Birçok kuruluş, harici API'ler için REST ve dahili ön uçtan arka uca iletişim için GraphQL'in her ikisini de kullanır.

Odoo'yu diğer iş sistemlerine nasıl entegre ederim?

Odoo, entegrasyon için JSON-RPC, XML-RPC ve REST API'leri (Odoo 17+) sağlar. Gerçek zamanlı entegrasyon için Odoo'nun API'lerini kullanan ve bunları diğer sistemlere sunan bir ara yazılım katmanı (NestJS, FastAPI) oluşturun. Olay odaklı entegrasyon için kayıtlar değiştiğinde web kancalarını tetiklemek için Odoo'nun otomatik eylemlerini kullanın. ECOSIRE, Odoo entegrasyon mimarisinde uzmanlaşmıştır — entegrasyon hizmetlerimize bakın.

Web kancaları ile mesaj kuyrukları arasındaki fark nedir?

Web kancaları HTTP geri aramalarıdır — Sistem A, bir olay meydana geldiğinde Sistem B'ye bir HTTP POST gönderir. Basittirler ve geniş çapta desteklenirler ancak garantili teslimattan yoksundurlar. İleti kuyrukları (RabbitMQ, Kafka, SQS) olayları kalıcı olarak depolar ve bunları yapılandırılabilir yeniden deneme, sıralama ve yayma garantileriyle sunar. Harici sağlayıcı entegrasyonu için web kancalarını kullanın (Stripe, Shopify); Dahili hizmetten hizmete iletişim için mesaj kuyruklarını kullanın.

Üçüncü taraf sağlayıcıların API hızı sınırlarını nasıl yönetirim?

Sağlayıcının ücret sınırlarına uygun bir istek kuyruğu uygulayın. Sağlayıcının oran sınırı penceresiyle senkronize edilmiş bir belirteç grubu algoritması kullanarak istek sayınızı izleyin. API çağrılarını azaltmak için yanıtları agresif bir şekilde önbelleğe alın. Web kancası ağırlıklı entegrasyonlar için web kancalarını eşzamansız olarak işleyin, böylece HTTP yanıtı işlem süresinden bağımsız olarak hemen geri döner.

Özel bir API ağ geçidi mi oluşturmalıyım yoksa yönetilen bir hizmet mi kullanmalıyım?

Çoğu işletme için, yönetilen bir API ağ geçidi (AWS API Ağ Geçidi, Cloudflare Çalışanları, Azure APIM) doğru seçimdir; daha az operasyonel ek yük, yerleşik ölçeklendirme ve kimlik doğrulama, hız sınırlama ve izleme için önceden oluşturulmuş özellikler. Yalnızca yönetilen hizmetlerin karşılayamayacağı belirli gereksinimleriniz varsa (özel kimlik doğrulama protokolleri, karmaşık istek dönüşümü veya katı veri yerleşimi gereksinimleri) özel bir ağ geçidi oluşturun.

Mevcut entegrasyonları bozmadan API'leri nasıl sürümlendirebilirim?

URL yolu sürümlendirmesini (/v1/, /v2/) kullanın ve bir sürümde geriye dönük uyumluluğu koruyun. Sürümü artırmadan ek değişiklikler (yeni alanlar, yeni uç noktalar) yapın. Yalnızca değişikliklerin bozulması kaçınılmaz olduğunda yeni bir sürüm oluşturun. Kullanımdan kaldırma zaman çizelgelerini önceden (6+ ay) iletin ve geçiş belgelerini sağlayın.

API entegrasyonları için hangi izlemeyi yapmalıyım?

Beş temel ölçümü izleyin: hata oranı (4xx/5xx yanıtlarının yüzdesi), gecikme (p50, p95, p99), üretim (saniye başına istek sayısı), kullanılabilirlik (çalışma süresi yüzdesi) ve doygunluk (oran limitlerine veya kapasiteye ne kadar yakınsınız). Hata oranındaki ani artışlar, taban çizgisinin üzerindeki gecikme artışları ve geçersiz kuyruk derinliği hakkında uyarılar ayarlayın. Dağıtılmış izleme (OpenTelemetry, Jaeger), birden fazla hizmete yayılan sorunların hatalarını ayıklamak için gereklidir.

---

Dayanıklı Entegrasyonlar Oluşturma

API entegrasyon mimarisi, iş teknolojisi yığınınızın bağ dokusudur. Seçtiğiniz modeller (istek-yanıt veya olay odaklı, eşzamanlı veya eşzamansız, merkezi ağ geçidi veya noktadan noktaya) işletmeniz büyüdükçe entegrasyonlarınızın ne kadar dayanıklı, sürdürülebilir ve ölçeklenebilir olacağını belirler.

Açık API sözleşmeleriyle başlayın, hata işlemeye yatırım yapın ve mantığı ilk günden itibaren yeniden deneyin ve entegrasyon katmanınızı temel uygulama hizmetlerinizle aynı titizlikle izleyin.

ECOSIRE'ın entegrasyon hizmetleri işletmelerin kurumsal entegrasyon mimarileri tasarlamasına ve uygulamasına yardımcı olur; Odoo ERP, Shopify ticareti, ödeme işlemcileri ve üçüncü taraf hizmetlerini ölçeklenebilir modellerle birbirine bağlar. Entegrasyon mimarinizi görüşmek için bize ulaşın.