API Nedir, İşletmeler İçin Neden Kritik Hale Geldi?
API (uygulama programlama arayüzü), iki yazılımın birbiriyle konuşmasını sağlayan sözleşmedir. İnsan arayüzü ekranlarla, düğmelerle ve formlarla konuşurken; makineler tanımlı adresler, belirlenmiş veri biçimleri ve üzerinde anlaşılmış kurallar üzerinden konuşur. Bir kargo firmasının takip numarasını sorgulayabilmeniz, ödeme sayfanızın bankayla haberleşmesi, mobil uygulamanızın web sitenizle aynı siparişi görmesi ve muhasebe programınıza faturaların kendiliğinden düşmesi; hepsi bir API'nin arka planda çalışmasıyla mümkün olur.
Bir zamanlar API, yalnızca büyük teknoloji şirketlerinin gündemindeydi. Bugün ise orta ölçekli bir işletmenin bile içinde en az beş altı ayrı yazılım dönüyor: web sitesi, e-ticaret altyapısı, muhasebe programı, stok sistemi, CRM, kargo paneli, e-fatura sağlayıcısı. Bu sistemler birbirine bağlı değilse, aralarındaki köprüyü insanlar kurar — yani birileri her gün aynı veriyi bir ekrandan okuyup diğerine yazar. Bu köprü yavaştır, pahalıdır ve hata yapar. Entegrasyon, işletmelerin fark ettiğinden çok daha büyük bir maliyet kalemini ortadan kaldırır.
API'nin ikinci ve daha stratejik boyutu ise ürününüzün kendisini başkalarına açmaktır. Bayilerinizin kendi sistemlerinden sipariş verebilmesi, iş ortaklarınızın stok ve fiyat bilgisini otomatik çekebilmesi ya da bir yazılım evinin sizin altyapınız üzerine çözüm geliştirebilmesi; ancak yayınlanmış, belgelenmiş ve güvenli bir API ile mümkündür. Böyle bir arayüz, teknik bir çıktı olmanın ötesinde ticari bir kanaldır.
Marmaragen olarak 2015'ten beri İstanbul Maltepe'den hizmet veriyoruz; 150'yi aşkın projede hem sıfırdan API tasarladık hem de birbirinden habersiz çalışan sistemleri konuşturduk. Bu sayfada API türlerini, tasarım ve dokümantasyon yaklaşımımızı, güvenlik ve performans pratiklerimizi, üçüncü parti entegrasyon sürecimizi ve fiyatı belirleyen faktörleri anlatıyoruz. Amacımız, bir kez yazılıp unutulan değil; yıllar boyunca güvenle geliştirilebilen bir arayüz bırakmak.
Marmaragen API Geliştirme Yaklaşımı
Önce sözleşme: tasarımdan başlayan geliştirme
API geliştirmeye koddan değil sözleşmeden başlıyoruz. Hangi kaynaklar dışarıya açılacak, her kaynak hangi alanları taşıyacak, hangi işlemler mümkün olacak, hatalar nasıl bir yapıda dönecek ve sayfalama, filtreleme, sıralama nasıl standartlaşacak; bunlar tek satır kod yazılmadan önce belgelenir. Bu belge, yalnızca teknik bir doküman değil ekipler arası bir anlaşmadır.
Bu yaklaşımın en somut faydası paralel çalışmadır. Sözleşme onaylandığı anda arayüz ekibi sahte veriyle geliştirmeye başlayabilir, mobil ekip ekranlarını kurabilir, dış paydaş entegrasyonunu planlayabilir. Kimse kimsenin işini bitirmesini beklemez. İkinci faydası ise tutarlılıktır: aynı kavram her uç noktada aynı isimle, aynı biçimde geçer. Kimi yerde "musteriId", kimi yerde "customer_id" yazan bir API, onu tüketen her ekibe her gün küçük bir vergi ödetir.
Kararlılık ve versiyonlama: yayındaki servisi bozmadan geliştirmek
Yayına çıkmış bir API'nin en değerli özelliği kararlılığıdır. Sizin bir alanı yeniden adlandırmanız, onu tüketen mobil uygulamanın çökmesi anlamına gelebilir — üstelik kullanıcıların uygulamayı ne zaman güncelleyeceğini kontrol edemezsiniz. Bu yüzden değişiklikleri iki kategoriye ayırırız: uyumluluğu bozmayanlar (yeni alan eklemek, yeni uç nokta açmak) doğrudan yayınlanır; uyumluluğu bozanlar ise yeni bir sürüm altında hayata geçer.
Sürüm geçişlerini ilan edilmiş takvimlerle yönetiriz: yeni sürüm yayınlandığında eski sürüm hemen kapatılmaz, belirlenen geçiş süresi boyunca çalışmaya devam eder ve tüketicilere önceden bilgi verilir. Kullanımdan kaldırılacak alanlar dokümantasyonda önceden işaretlenir. Böylece hem gelişmeyi durdurmamış hem de kimsenin sistemini habersiz bozmamış olursunuz.
Gözlemlenebilirlik: ne olduğunu bilmek
Bir API'yi yayınlamak işin yarısıdır; diğer yarısı onu izlemektir. Hangi uç nokta ne sıklıkta çağrılıyor, ortalama ve en kötü yanıt süreleri ne, hata oranı hangi istemcide yükseliyor, hangi entegrasyon sessizce başarısız oluyor? Bu sorulara cevap veremeyen bir servis, sorunları müşteri şikâyetiyle öğrenir. Kurduğumuz sistemlerde istek kayıtları, metrikler ve uyarı kuralları en baştan devrededir. Her isteğe izlenebilir bir kimlik atarız; bir müşteri "üç gün önce şu saatte hata aldım" dediğinde o isteğin tüm yolculuğunu geriye dönük izleyebiliriz.
API Geliştirme Sürecimiz: Adım Adım
Entegrasyon projelerinin en sık başarısızlık sebebi teknik zorluk değil, belirsizliktir: hangi verinin kimden geleceği, hata durumunda ne yapılacağı ve testin nasıl yürütüleceği netleşmeden başlanan projeler uzar. Sürecimiz bu belirsizlikleri baştan kapatacak şekilde kurgulanmıştır:
- İhtiyaç ve veri akışı analizi — Hangi sistemlerin birbirine bağlanacağı, hangi verinin hangi yönde aktığı, gerçek zamanlı mı yoksa periyodik mi çalışacağı ve hangi sistemin hangi veride tek doğru kaynak olduğu çıkarılır. Mevcut sistemlerin dokümantasyonu ve kısıtları incelenir.
- Sözleşme tasarımı — Kaynaklar, uç noktalar, veri şemaları, hata kodları ve yetki modeli tasarlanır; OpenAPI biçiminde belgelenir. Sözleşme onaylanmadan geliştirmeye geçilmez, çünkü bu aşamada yapılan bir düzeltme kod yazıldıktan sonrakinin çok küçük bir bölümü kadar maliyetlidir.
- Geliştirme ve dokümantasyon — Uç noktalar sözleşmeye sadık biçimde kodlanır; doğrulama, hata yönetimi, sayfalama ve yetki kontrolleri standart bir çerçevede uygulanır. Swagger arayüzü ile dokümantasyon canlı olarak denenebilir hale gelir.
- Test, güvenlik ve yük denemesi — Uç noktalar otomatik testlerle doğrulanır; yetkisiz erişim, hatalı girdi ve sınır durumları senaryolarla denenir. Oran sınırlama kuralları ayarlanır, önbellek stratejisi ve yanıt süreleri yük altında ölçülür.
- Yayın, izleme ve sürüm yönetimi — Servis yayına alınır, metrik ve uyarı kuralları devreye girer. Tüketici ekiplere erişim anahtarları ve dokümantasyon teslim edilir; sonraki geliştirmeler versiyonlama disipliniyle sürdürülür.
API Türleri ve Hangi Senaryoda Hangisi
Her ihtiyaca tek bir yaklaşım dayatmıyoruz. Üç ana modeli, güçlü ve zayıf yanlarını bilerek kullanıyoruz.
RESTful API
Kaynak odaklı, HTTP'nin doğal kurallarını kullanan ve bugün en yaygın kabul gören modeldir. Adreslerin anlaşılır olması, standart durum kodları ve önbelleklenebilirliği; onu özellikle dış paydaşlara açılan servislerde güçlü kılar. Bir bayinin ya da iş ortağının teknik ekibi, REST API'yi ayrı bir eğitim almadan tüketebilir. Sayfalama, filtreleme, sıralama ve koşullu istek desteklerini tutarlı bir standartla kurgular; her uç noktanın aynı mantıkla davranmasını sağlarız.
GraphQL
İstemcinin ihtiyacı olan alanları tek bir sorguda, kendi belirlediği şekilde talep etmesini sağlar. Farklı ekranların farklı veri kümelerine ihtiyaç duyduğu mobil uygulamalarda ve zengin yönetim panellerinde; on ayrı isteği tek isteğe indirerek hem ağ trafiğini hem de gecikmeyi azaltır. Buna karşılık önbellekleme ve yetkilendirme daha dikkatli kurgulanmak zorundadır; kontrolsüz bırakılan derin sorgular sunucuyu zorlayabilir. Bu yüzden sorgu derinliği ve karmaşıklık sınırlarını en baştan tanımlarız.
WebSocket ve gerçek zamanlı iletişim
Bazı senaryolarda istemcinin sürekli "yeni bir şey var mı?" diye sorması hem verimsiz hem yavaştır. Canlı destek sohbeti, anlık bildirim, kurye takip ekranı, canlı fiyat tablosu ve eşzamanlı düzenleme gibi ihtiyaçlarda kalıcı bağlantı kuran WebSocket tabanlı çözümler üretiriz. Bağlantı koptuğunda otomatik yeniden bağlanma, kaçırılan mesajların telafisi ve ölçeklenirken bağlantıların dağıtımı bu tasarımın ayrılmaz parçalarıdır.
Webhook'lar
Bazen veri sizden değil, size doğru akmalıdır. Ödeme onayı, kargo durumu değişikliği veya dış sistemdeki bir kayıt güncellemesi gerçekleştiğinde, karşı tarafın sizi haberdar etmesi çok daha verimlidir. Webhook uçlarını tasarlarken imza doğrulaması, tekrar eden bildirimlere karşı bir kez işleme (idempotency) garantisi ve başarısız bildirimler için yeniden deneme kuyruğu kurarız; çünkü bu uçlar sessizce çalışır ve arızası geç fark edilir.
Swagger/OpenAPI Dokümantasyonu ve Versiyonlama
Dokümante edilmemiş bir API, pratikte var olmayan bir API'dir. Onu tüketecek geliştirici her alanı deneme yanılmayla keşfetmek zorunda kalır; sizin ekibiniz de aynı soruları defalarca cevaplar. Bu yüzden dokümantasyonu teslimin isteğe bağlı bir eki değil, zorunlu bir parçası sayıyoruz.
OpenAPI standardında yazılan tanım dosyası hem insan hem makine tarafından okunabilir. Swagger arayüzü üzerinden her uç nokta tarayıcıdan denenebilir; parametreler, örnek istek ve yanıtlar, zorunlu alanlar ve hata kodları tek ekranda görünür. Aynı tanım dosyasından istemci kütüphaneleri üretilebilir, otomatik testler beslenebilir. En önemlisi, dokümantasyon kodun yanında yaşadığı için güncelliğini yitirmez — "doküman var ama iki sürüm geride" durumu, dokümantasyonun hiç olmamasından daha zararlıdır.
Versiyonlama tarafında adres tabanlı sürümleme genellikle en anlaşılır yöntemdir; hangi sürümün konuşulduğu istekten bakılarak anlaşılır. Sürüm politikasını yazılı hale getiririz: hangi tür değişikliklerin yeni sürüm gerektirdiği, eski sürümlerin ne kadar süre destekleneceği ve kullanımdan kaldırma bildiriminin nasıl yapılacağı baştan bellidir. Bu netlik, sizin API'nizi tüketen ekiplerin size güvenmesini sağlar.
API Güvenliği: OAuth 2.0, Anahtar Yönetimi ve Erişim Kontrolü
Bir API, sisteminizin dışarıya açılan kapısıdır; dolayısıyla kimin, neye, ne kadar erişebileceği en kritik tasarım kararıdır. Kimlik doğrulamada senaryoya göre farklı modeller kullanırız. Sunucudan sunucuya çalışan entegrasyonlarda anahtar ve gizli anahtar ikilisi genellikle yeterlidir. Son kullanıcı adına işlem yapılan ve üçüncü parti uygulamaların devreye girdiği senaryolarda ise OAuth 2.0 akışlarını uygularız: kullanıcı parolasını hiçbir zaman üçüncü tarafa vermeden, sınırlı kapsamda ve süreli yetki devri sağlanır.
Anahtar yönetimini disiplinle ele alırız. Her tüketiciye ayrı anahtar verilir; böylece bir anahtar sızdığında yalnızca o taraf iptal edilir. Anahtarlar kapsam (scope) ile sınırlandırılır — okuma yetkisi olan bir entegrasyon veri silemez. Anahtar döndürme (rotation) desteği baştan kurulur ki bir değişim gerektiğinde servis kesintiye uğramasın. Test ve üretim ortamları için ayrı anahtar setleri tanımlanır; test verisiyle gerçek veri hiçbir zaman aynı kapıdan geçmez.
Yetkilendirmede rolün ötesine geçip kaynak sahipliğini kontrol ederiz: kimliği doğrulanmış bir istemci, yalnızca kendisine ait kayıtlara ulaşabilir. Tüm trafik TLS üzerinden taşınır, hassas veriler yanıtlarda gereksiz yere yer almaz ve kayıtlara asla yazılmaz. Girdi doğrulama sunucu tarafında şemaya göre yapılır; beklenmeyen alanlar sessizce kabul edilmez. Kapsamlı güvenlik denetimi ve sızma testi ihtiyacında web güvenliği hizmetimiz devreye girer; servisin altındaki sunucu tarafı mimarisini ise backend geliştirme sayfamızda anlatıyoruz.
Üçüncü Parti Entegrasyonlar
Entegrasyon projelerinde asıl iş, mutlu senaryoyu çalıştırmak değil; mutsuz senaryoları yönetmektir. Dış servis yavaşladığında, geçici olarak yanıt vermediğinde ya da beklenmedik bir hata döndürdüğünde sisteminizin ne yapacağı önceden tasarlanmalıdır. Zaman aşımı sınırları, kademeli bekleyerek yeniden deneme, devre kesici (circuit breaker) mantığı ve aynı işlemin iki kez uygulanmasını engelleyen tekrarsızlık kontrolleri; her entegrasyonda standart olarak kurguladığımız savunmalardır.
Ödeme entegrasyonları en hassas başlıktır: kart verisinin sizin sisteminize hiç düşmediği akışları tercih eder, ödeme onaylarını yalnızca sağlayıcıdan gelen doğrulanmış bildirimlerle işleriz. Sipariş ve ödeme durumlarını ayrı ayrı takip eder, yarım kalmış işlemler için mutabakat mekanizması kurarız. Mağaza tarafındaki uçtan uca kurulum için e-ticaret hizmetimize göz atabilirsiniz.
Harita ve konum servisleri ile adres doğrulama, mesafe hesaplama, teslimat bölgesi tanımlama ve canlı takip ekranları geliştiriyoruz. Bu servislerde çağrı maliyetleri hızla artabildiği için sonuçları akıllıca önbelleğe alır, gereksiz sorguları en aza indiririz. Sosyal medya entegrasyonlarında içerik paylaşımı, sosyal giriş ve veri çekme akışlarını platformların değişken kurallarını takip ederek kurarız. E-posta ve SMS sağlayıcılarında gönderim, teslim durumu takibi ve şablon yönetimini tek bir soyutlama üzerinden yönetiriz; sağlayıcı değişikliği uygulama kodunu etkilemez. Muhasebe, e-fatura, ERP ve kargo entegrasyonlarında ise veri eşleştirme kuralları ve mutabakat raporları işin en kritik parçasıdır; hangi kaydın hangi sistemde doğru kabul edileceği yazılı olarak netleştirilir.
Çoklu İstemci: Web, Mobil, Panel ve İş Ortakları Aynı Servisi Kullanınca
İyi tasarlanmış bir API'nin en büyük ekonomik faydası, aynı iş mantığının tek yerde yaşamasıdır. Web siteniz, mobil uygulamanız, yönetim paneliniz ve bayi portalınız aynı servisi tükettiğinde; bir kural değiştiğinde dört ayrı yerde güncelleme yapmak zorunda kalmazsınız. Bu, hem geliştirme maliyetini hem de "web'de şu fiyat çıkıyor ama uygulamada başka" türünden tutarsızlıkları ortadan kaldırır.
Ancak çoklu istemci, tasarımı da zorlar; çünkü her istemcinin ihtiyacı aynı değildir. Mobil uygulama, zayıf bağlantıda az veri ve az istek ister; yönetim paneli aynı kaydın tüm ayrıntısını görmek ister; iş ortağının sistemi ise yalnızca kendisiyle ilgili alt kümeyi görebilmelidir. Bu ihtiyaçları alan seçimi, farklı temsil biçimleri ve kapsam tabanlı yetkilendirme ile karşılarız; her istemci için ayrı bir servis yazmak yerine tek servisi esnek tasarlarız.
Mobil tarafta ek olarak çevrimdışı senaryoları da düşünürüz: bağlantı koptuğunda biriken işlemlerin sonradan sırayla gönderilmesi, aynı işlemin iki kez işlenmemesi ve sunucu ile istemci arasındaki çakışmaların hangi kurala göre çözüleceği önceden tanımlanır. Uygulama tarafındaki geliştirme ihtiyacınız için mobil uygulama hizmetimize, arayüz katmanı için ise frontend geliştirme sayfamıza göz atabilirsiniz.
Performans: Rate Limiting, Gateway, Caching ve Load Balancing
Bir API'nin başarısı bazen kendi sorununa dönüşür: kullanım arttıkça yanıt süreleri uzar, tek bir kötü davranan istemci tüm servisi yavaşlatabilir. Bu yüzden performansı ve korumayı birlikte tasarlarız.
Rate limiting, hem kötüye kullanıma hem de kazara oluşan aşırı yüke karşı ilk savunmadır. Her istemci için zaman penceresi başına istek sınırı tanımlar, sınıra yaklaşıldığını bildiren başlıklarla tüketiciyi önceden uyarırız; ani kesme yerine öngörülebilir bir davranış sunmak, entegrasyon ekiplerinin işini kolaylaştırır. Kritik ve maliyetli uç noktalar için ayrı, daha sıkı sınırlar tanımlanabilir.
API gateway katmanı; kimlik doğrulama, oran sınırlama, istek kaydı, yönlendirme ve sürüm eşlemesi gibi ortak sorumlulukları tek bir noktada toplar. Böylece her servis bu işleri ayrı ayrı üstlenmez, kurallar merkezî olarak yönetilir ve yeni bir servis eklendiğinde aynı korumaları otomatik olarak devralır.
Caching tarafında iki katman kullanırız. İstemci tarafı önbelleklemeyi doğru HTTP başlıklarıyla teşvik eder, değişmeyen veriyi tekrar tekrar göndermeyiz. Sunucu tarafında ise sık okunan ve seyrek değişen veriyi bellekte tutar, geçersiz kılma (invalidation) kurallarını veri değiştiği anda tetikleriz — çünkü bayat veri sunan bir önbellek, yavaş bir servisten daha zararlıdır. Load balancing ile trafik birden fazla örneğe dağıtılır; sağlık kontrolleri sayesinde yanıt vermeyen örnek otomatik olarak devre dışı kalır ve yük artışında yeni örnekler devreye alınır. Barındırma ve ölçekleme tarafını uçtan uca üstlenmemizi isterseniz web hosting hizmetimizle tek elden yönetilen bir çözüm sunuyoruz.
Son olarak, performans iyileştirmelerinin ölçümle başlaması gerektiğini hatırlatalım. Hangi uç noktanın gerçekten yavaş olduğunu tahminle değil, gerçek trafiğin dağılımına bakarak belirleriz; çoğu zaman toplam sürenin büyük kısmını, çağrı sayısı az ama maliyeti yüksek birkaç uç nokta üretir. Önce onları düzeltmek, her yeri optimize etmeye çalışmaktan hem daha hızlı hem daha ucuz sonuç verir.
API Geliştirme Fiyatlarını Belirleyen Faktörler
API projelerinde maliyeti belirleyen şey uç nokta sayısı değil, arkasındaki iş kurallarının ve dış bağımlılıkların karmaşıklığıdır. Teklifimizi şekillendiren ana kalemler şunlardır:
- Uç nokta sayısı ve veri modelinin derinliği — Kaynak çeşitliliği, ilişkilerin karmaşıklığı ve her uç noktanın taşıdığı iş kuralı yükü.
- Entegre edilecek dış sistem sayısı — Her sağlayıcının kendi dokümantasyonu, test ortamı, kimlik doğrulama modeli ve hata senaryoları vardır; entegrasyonlar tek tek fiyatlanır.
- Dış sistemin dokümantasyon kalitesi — Belgeleri güncel ve test ortamı sağlıklı olan bir servise entegre olmak ile eksik belgelenmiş, deneyerek keşfedilen bir sisteme bağlanmak aynı iş değildir.
- Güvenlik gereksinimleri — Basit anahtar doğrulaması ile tam OAuth 2.0 akışları, kapsam yönetimi ve denetim kayıtları farklı efor gerektirir.
- Trafik ve performans beklentisi — Gateway, önbellek katmanı, oran sınırlama altyapısı ve yatay ölçekleme kurulumu ek mühendislik demektir.
- Gerçek zamanlı ihtiyaçlar — WebSocket tabanlı kalıcı bağlantılar ve olay yayını, klasik istek-yanıt modeline göre daha fazla tasarım ve test gerektirir.
- Dokümantasyon ve destek kapsamı — Dış paydaşlara açılan servislerde geliştirici desteği, örnek kod ve sürüm geçiş danışmanlığı ayrı bir kalem olarak planlanır.
Analiz sonrasında kalem kalem yazılmış, kapsamı net bir teklif alırsınız; hangi entegrasyonun kapsamda olduğu ve kapsam dışı taleplerin nasıl fiyatlanacağı baştan yazılır. Planlarımızı inceleyebilir veya doğrudan arayarak projenize özel teklif isteyebilirsiniz. Servisi tüketecek arayüz tarafını da bizim geliştirmemizi isterseniz web yazılım ve web tasarım hizmetlerimizle bütünleşik ilerleyebiliriz.
Neden Marmaragen?
- 8+ yıl deneyim, 150+ proje: 2015'ten beri İstanbul Maltepe'den Türkiye geneline hizmet veriyoruz; 250'den fazla müşteriyle çalıştık.
- Sözleşmeyle başlayan tasarım: Kod yazılmadan önce onaylanan OpenAPI sözleşmesi sayesinde ekipler paralel çalışır, sürprizler entegrasyon gününe kalmaz.
- Dokümantasyon teslimin parçası: Tarayıcıdan denenebilen, kodla birlikte güncellenen ve güncelliğini yitirmeyen bir doküman bırakıyoruz.
- Bozmayan versiyonlama: Yayındaki servisi kırmadan geliştiriyor, sürüm geçişlerini ilan edilmiş takvimlerle yönetiyoruz.
- Mutsuz senaryolara hazır entegrasyonlar: Zaman aşımı, yeniden deneme, mutabakat ve tekrarsızlık kontrolleri her entegrasyonda standarttır.
- Güvenlik ve performans birlikte: OAuth 2.0, kapsamlı anahtar yönetimi, oran sınırlama, gateway ve önbellekleme aynı tasarımın parçaları.
- Tek muhatap: Servis katmanı, arayüz, barındırma ve güvenlik aynı ekipte; entegrasyon sorununda firmalar arasında top çevrilmez.