Web Yazılımında API Entegrasyonu Nedir? Kapsamlı Teknik Rehber

API, "Application Programming Interface" yani Uygulama Programlama Arayüzü ifadesinin kısaltmasıdır. İstemci uygulama belirli bir adrese HTTPS isteği gönderir; istek başlığında kimlik bilgisi, gövdesinde genellikle JSON formatında veri bulunur. Sunucu kimliği doğrular, yetkiyi kontrol eder, işlemi yapar ve bir HTTP durum koduyla yanıt döner: 200 başarıyı, 401 yetki sorununu, 500 sunucu hatasını gösterir. Bu kodlar sorunun kaynağını anında belli eder.

REST, web API'leri için fiili standart hâline gelmiş mimari yaklaşımdır. HTTP'nin GET, POST, PUT ve DELETE metotlarını kullanır, genellikle JSON formatında veri döner. Basitliği, önbellek dostu yapısı ve her programlama dilinde geniş kütüphane desteği sayesinde yeni projelerde varsayılan tercihtir. Sabit veri yapılı, kaynak odaklı servislerde hem geliştirme hem bakım maliyeti düşüktür.

SOAP, XML tabanlı ve sıkı sözleşmeli (WSDL) eski nesil bir protokoldür; yeni projelerde nadiren tercih edilir ama Türkiye'de fiilen zorunlu olduğu alanlar vardır. GİB'in e-Fatura web servisleri, birçok banka ve kamu sistemi hâlâ SOAP ile çalışır. Bu yüzden entegrasyon katmanınızın REST'in yanında SOAP'ı da konuşabilmesi, XML-JSON dönüşümünü bir adaptör katmanında çözmesi gerekir.

GraphQL, istemcinin tek istekte yalnızca ihtiyaç duyduğu alanları çekmesini sağlar; çok ekranlı, mobil ağırlıklı ve veri ihtiyacı ekrandan ekrana değişen projelerde trafiği belirgin azaltır. REST ise basitliği, önbelleklenebilirliği ve olgun araç ekosistemiyle kaynak odaklı servislerde daha pratiktir. Karar, istemci çeşitliliğine ve veri karmaşıklığına göre verilir: tek tip istemci ve sabit veri yapısında REST, çeşitlenen istemcilerde GraphQL öne çıkar.

Fark yöndedir: klasik API kullanımında veriyi siz sorarsınız (pull), webhook'ta ise olay gerçekleştiğinde karşı sistem sizin adresinize bildirim gönderir (push). Ödeme onaylandı, kargo teslim edildi gibi olaylarda sürekli sorgulama (polling) yerine webhook kullanmak hem gecikmeyi hem sunucu yükünü azaltır. Sağlam bir webhook tasarımında imza doğrulaması, mükerrer bildirim ayıklama (idempotency) ve başarısız teslimde yeniden deneme bulunur.

Açık (open) API'ler kayıt olan herkese açıktır; harita, SMS ve ödeme servisleri bu sınıftadır. Partner API'ler yalnızca sözleşmeli iş ortaklarına açılır; pazaryeri ve banka entegrasyonlarında olduğu gibi IP kısıtlaması ve ek doğrulama içerir. Dahili (internal) API'ler ise dış dünyaya kapalıdır; şirketin web, mobil ve arka ofis uygulamalarının ortak iş mantığını paylaşması için kullanılır. Tür seçimi, güvenlik modelini ve dokümantasyon kapsamını doğrudan belirler.

API anahtarı, istemciyi tanıtan benzersiz bir kimlik dizesidir; çoğu serviste yönetim paneli üzerinden üretilir ve istek başlığında gönderilir. Güvenli kullanım için anahtar asla kaynak koda veya sürüm kontrolüne (Git) yazılmaz; ortam değişkeni ya da vault gibi gizli anahtar yöneticisinde tutulur, test ve canlı ortam için ayrı anahtarlar kullanılır ve düzenli aralıklarla yenilenir. Sızan bir anahtar, sizin adınıza sınırsız istek atılabilmesi demektir.

Temel katmanlar şunlardır: TLS ile şifreli iletişim; kimlik doğrulamada API anahtarı, JWT, OAuth 2.0 veya şirketler arası hatlarda karşılıklı TLS (mTLS); rol bazlı yetkilendirme; girdi doğrulama; rate limiting ve merkezi loglama. OWASP API Security Top 10 listesi düzenli denetim çerçevesi olarak kullanılır. KVKK kapsamında loglarda kimlik ve kart bilgisi gibi hassas alanların maskelenmesi de güvenliğin parçasıdır.

Rate limiting, bir istemcinin belirli sürede gönderebileceği istek sayısını sınırlamaktır; örneğin dakikada 60 istek. Kötü niyetli yüklenme (DDoS), hatalı döngüye giren bir istemcinin sunucuyu boğması ve adil olmayan kaynak kullanımı bu sayede engellenir. Entegrasyon yaparken karşı servisin limitlerini bilmek de kritiktir: toplu veri aktarımında limit aşımı, isteklerin reddedilmesine ve senkronun bozulmasına yol açar.

OpenAPI (eski adıyla Swagger), bir API'nin tüm uç noktalarını, parametrelerini, örnek istek-yanıtlarını ve hata kodlarını standart biçimde tanımlayan formattır. İyi dokümantasyon, entegrasyonu yapan ekibin API'yi tahminle değil belgeye bakarak kullanmasını sağlar; entegrasyon süresini kısaltır, destek yükünü azaltır ve yıllar sonra devir ile bakımı kolaylaştırır. Belgesiz API, her yeni geliştirici için baştan keşif maliyeti demektir.

Sandbox, gerçek veriye dokunmadan API'yi sahte verilerle deneyebileceğiniz izole test ortamıdır; ödeme, iade ve iptal gibi kritik akışlar önce burada doğrulanır. Testler tamamlandığında canlı API anahtarları devreye alınır, sınırlı kapsamlı bir pilot dönem çalışılır ve geri dönüş (rollback) planı hazır tutulur. Kademeli geçiş, olası bir hatanın etkisini küçük tutmanın en güvenli yoludur. Edge Bilişim'in uyguladığı yöntemde canlıya geçiş mesai bitiminde değil, işlem yoğunluğunun düşük olduğu bir gün başında yapılır; ilk gün akan kayıtlar karşı sistemdeki karşılıklarıyla tek tek karşılaştırılır ve entegrasyon kapatma anahtarı (kill switch) ilk hafta boyunca panelde açık bırakılır.

İyi dokümante edilmiş tek bir servisin entegrasyonu genellikle birkaç gün ile iki hafta arasında tamamlanır. Süreyi uzatan etkenler servis sayısı, karşı API'nin dokümantasyon kalitesi, veri eşleştirme karmaşıklığı ve test-pilot kapsamıdır. Çok sistemli B2B veya ERP projeleri 4-12 haftaya yayılabilir; paralel pilot çalışması yapılan mutabakat senaryolarında takvime yaklaşık bir aylık doğrulama dönemi de eklenir.

Maliyeti servis sayısı, dokümantasyon kalitesi, veri eşleştirme karmaşıklığı, güvenlik gereksinimleri ve test kapsamı belirler. 2026 itibarıyla Türkiye'de tek servisli standart bir özel entegrasyon teklifi çoğunlukla 30.000-100.000 TL aralığında şekillenir; çok sistemli ERP ve B2B projelerinde bütçe birkaç yüz bin TL'yi bulabilir. Aylık abonelikli hazır konektörler standart senaryolarda daha ekonomiktir; özel iş kuralları devreye girdiğinde özel geliştirme gerekir.

İyi tasarlanmış bir mimaride çökmez. Kritik istekler kuyruğa alınır, geçici hatalarda artan aralıklarla yeniden deneme (retry) yapılır, sürekli hata veren servise karşı devre kesici (circuit breaker) devreye girer. Servis düzeldiğinde bekleyen işlemler otomatik tamamlanır; idempotency anahtarları mükerrer kaydı önler. Böylece dış kesinti veri kaybına değil, en fazla kısa bir gecikmeye dönüşür.

Evet. Eski sistemin önüne bir API katmanı (wrapper) ve gerekirse veri dönüştürücü (adapter) konularak, çekirdek koda dokunmadan modern uygulamalarla konuşması sağlanır; bu, riskli bir baştan yazma sürecine girmeden entegrasyon imkânı verir. Aynı yaklaşım donanım tarafında da geçerlidir: üretim hattındaki terazi, barkod okuyucu ve sensörler IoT ve donanım API entegrasyonuyla web tabanlı sistemlere bağlanabilir.

Sipariş-stok senkronu, fatura aktarımı, kargo takibi, tahsilat mutabakatı ve SMS/e-posta bildirimleri en yaygın senaryolardır. Daha az bilinen ama getirisi yüksek örnekler de vardır: sözleşmelerin e-imza ve KEP entegrasyonuyla dijital imzalatılması, bayi siparişlerinin B2B API üzerinden doğrudan ERP'ye düşmesi, pazaryeri entegrasyon yazılımıyla Trendyol ve Hepsiburada siparişlerinin kendi paneline akması, yapay zeka asistanlarına temiz ve yapılandırılmış veri sunan özel uç noktalar. Kural basittir: iki sistem arasında elle düzenli kopyalanan her veri, bir entegrasyon adayıdır.

Ödeme tarafında iyzico, PayTR ve Param; kargoda Yurtiçi, Aras ve MNG; iletişimde SMS sağlayıcıları ve WhatsApp Business API en sık bağlanan servislerdir. Bunlara pazaryeri API'leri (Trendyol, Hepsiburada), Google Maps ve e-Fatura özel entegratörleri eklenir. Her servis kendi paneli üzerinden API anahtarı üretir; dokümantasyon kalitesi ve sandbox imkânı servisten servise ciddi fark gösterdiği için proje takvimi, bağlanacak servisin olgunluğuna göre planlanmalıdır.

Tek servisli basit senaryolarda — örneğin bir SMS API'sini web formuna bağlamak — dokümantasyonu takip eden bir geliştirici işi kendi başına çözebilir. Uzman desteği; birden fazla sistemin senkronu, veri eşleştirme kuralları, kesinti ve hata yönetimi, KVKK'ya uygun loglama gibi katmanlar devreye girdiğinde anlamlı hâle gelir. Yanlış kurgulanan bir entegrasyonu canlıda düzeltmenin maliyeti, çoğu zaman baştan doğru kurmanın birkaç katıdır.

Çoğu durumda evet. Sitenin altyapısı modernse mevcut kodun üzerine bir entegrasyon katmanı eklenir ve dış servislerle bağlantı kurulur. Altyapı çok eskiyse önce sınırlı bir modernizasyon önerilir; örneğin API isteklerini yönetecek ayrı bir servis katmanı kurulur, böylece ana site riske atılmadan entegrasyon kazanılır. Karar için mevcut teknoloji yığınının ve sunucu ortamının incelenmesi yeterlidir. Edge Bilişim bu incelemeyi mevcut sitenin sunucu sürümleri, oturum yapısı ve dış istek atma yetkisi üzerinden yapıyor; entegrasyon katmanını ana siteden ayrı çalışan bir servis olarak konumlandırdığımız için bir sorun çıktığında sadece o servis durduruluyor, mağaza ve site açık kalıyor. Bu yaklaşımı hem mevcut projelere hem sıfırdan kurulan e-ticaret altyapılarına aynı şekilde uyguluyoruz.