İşletmeler İçin API-First Özel Yazılım Yaklaşımı Nasıl Planlanır?

Bir özel yazılımın ilk sürümünde yalnızca web paneli bulunabilir. Birkaç ay sonra mobil uygulama, bayi portalı, muhasebe bağlantısı, saha ekranı veya iş ortaklarına açılacak servisler gündeme geldiğinde mevcut sistemin dış dünyayla nasıl konuşacağı kritik hâle gelir. İş kuralları yalnızca ekranların içine gömülmüşse her yeni kanal aynı işlemleri yeniden geliştirmek zorunda kalabilir.

API-first yaklaşımı, API’yi proje sonunda eklenen teknik bağlantı olarak değil, yazılımın iş yeteneklerini sunan temel sözleşmelerden biri olarak ele alır. Önce hangi verinin, işlemin, hata sonucunun ve güvenlik kuralının sunulacağı tasarlanır; ardından web paneli, mobil uygulama ve entegrasyonlar bu sözleşme üzerinden geliştirilir. Bu rehber, API-first özel yazılım yaklaşımının işletmeler için ne ifade ettiğini ve hangi durumda nasıl planlanması gerektiğini açıklar.

API-first özel yazılım yaklaşımı nedir?

API-first, bir yazılımın işlevlerinin ekran tasarımından veya tek bir istemci uygulamadan önce açık bir API sözleşmesiyle tanımlanmasıdır. Sözleşme; kaynakları, işlemleri, istek alanlarını, yanıtları, hata durumlarını, kimlik doğrulamayı ve sürüm davranışını tarif eder. Kod bu sözleşmeyi uygulamak üzere geliştirilir.

Microsoft Azure Architecture Center, contract-first yaklaşımını önce API arayüzünün tasarlanması, ardından bu sözleşmeyi uygulayan kodun yazılması olarak açıklar Microsoft Azure Architecture Center. API-first bunun daha geniş proje yaklaşımıdır: sözleşme yalnızca doküman değil, ekiplerin paralel çalışmasını, testleri, yönetişimi ve ilerideki kanalları şekilliren ürün bileşenidir.

API-first ile sonradan API eklemek arasındaki fark nedir?

Implementation-first veya API-last yaklaşımında ekip önce ekranları ve arka uç kodunu geliştirir. Entegrasyon ihtiyacı çıktığında mevcut kodun bazı bölümleri dışarıya açılır. Bu yöntem küçük ve tek kanallı projede hızlı başlayabilir; ancak API’nin ekran ihtiyaçlarına göre şekillenmesi, tutarsız adlandırma ve veri sızıntısı gibi sorunlar oluşturabilir.

API-first her projede daha kısa teslim süresi vaat etmez. İlk fazda tek yönetim paneli bulunan ve dış bağlantı ihtimali düşük küçük bir uygulamada kapsamlı API yönetişimi gereksiz olabilir. Ancak birden fazla kanal, iş ortağı, entegrasyon veya ürünleşme hedefi bulunuyorsa erken sözleşme tasarımı ilerideki yeniden geliştirme ihtiyacını azaltabilir.

İşletmeler için hangi avantajları sağlar?

Web, mobil ve entegrasyonların aynı iş kurallarını kullanmasını sağlar

Sipariş oluşturma, stok ayırma veya onay verme kuralı yalnızca web ekranında uygulanırsa mobil uygulama aynı mantığı yeniden yazmak zorunda kalabilir. API-first yapıda iş kuralı sunucu tarafında merkezi olarak çalışır; istemciler işlem sonucunu aynı sözleşmeyle alır.

Bu yaklaşım, mobil uygulama geliştirme planı sonradan ortaya çıktığında mevcut iş kurallarının sıfırdan taşınmasını azaltır. Mobil arayüz farklı olabilir; ancak sipariş ve yetki sonucu web paneliyle tutarlı kalır.

Ekiplerin paralel çalışmasını kolaylaştırır

API sözleşmesi onaylandığında istemci ekibi gerçek servis tamamlanmadan mock sunucu veya örnek yanıtlarla ekran geliştirebilir. Arka uç ekibi aynı anda sözleşmenin davranışını uygulayabilir. Bu yöntem bağımlılığı tamamen kaldırmaz; fakat ekiplerin bekleme süresini azaltır.

OpenAPI Specification, HTTP API’lerini programlama dilinden bağımsız biçimde tanımlayan standart bir arayüz açıklaması sunar. İnsanların ve yazılımların kaynak koda erişmeden API yeteneklerini anlamasını amaçlar OpenAPI Specification. Bu makine tarafından okunabilir sözleşme; dokümantasyon, istemci üretimi, doğrulama ve test araçları için temel oluşturabilir.

İş ortaklarına açılabilecek kontrollü bir altyapı oluşturur

Bayi, tedarikçi, kargo firması veya müşteriye belirli işlemler sunulacaksa bütün iç sistemi açmak yerine yalnızca gerekli API yüzeyi yayınlanabilir. Hangi rolün hangi kaynağa erişeceği, hız sınırı, kayıt kapsamı ve denetim izi ayrı politika olarak tanımlanır.

API entegrasyonları işletme büyüdükçe çoğalabilir. API-first tasarım, her yeni bağlantının doğrudan veritabanına özel yöntemlerle bağlanması yerine kontrollü ve belgelenmiş bir katman kullanmasını destekler.

Teknoloji değişiminde iş sözleşmesini korumaya yardımcı olur

Web arayüzünün teknolojisi veya arka uçtaki veri saklama yöntemi değişebilir. API sözleşmesi geriye uyumlu kaldığı sürece istemcilerin aynı anda yeniden yazılması gerekmeyebilir. Bu ayrım, uygulamanın iç yapısıyla dışarıya sunduğu davranışı birbirinden uzaklaştırır.

Bu avantaj otomatik değildir. API doğrudan veritabanı tablosunu yansıtıyorsa iç veri modeli değiştiğinde sözleşme de kırılabilir. Kaynaklar işletmenin iş kavramlarına göre tasarlanmalı; iç tablo ve sınıf adları dış sözleşmeye kontrolsüz biçimde taşınmamalıdır.

API-first yaklaşımı mikroservis zorunluluğu değildir

API-first ile mikroservis kavramları sık birlikte kullanılsa da aynı şey değildir. Modüler monolit bir özel yazılım da iyi tasarlanmış API sözleşmeleri sunabilir. İşlevlerin tek dağıtım içinde çalışması, web ve mobil istemcilerin merkezi API üzerinden hizmet almasına engel değildir.

İlk aşamada çok sayıda mikroservis kurmak; ağ iletişimi, dağıtım, izleme ve veri tutarlılığı yükünü artırabilir. API-first kararının amacı sistemi parçalamak değil, işlevlerin dışarıya nasıl sunulacağını açık ve kararlı hâle getirmektir. Gerçek ölçek veya ekip bağımsızlığı gerektirdiğinde bazı modüller daha sonra ayrıştırılabilir.

Bu nedenle mimari karar şu sırayla verilmelidir:

1. İş alanlarını ve veri sahipliğini belirleyin.
2. İstemcilerin ihtiyaç duyduğu sözleşmeleri tasarlayın.
3. Modüllerin aynı uygulamada mı, ayrı hizmetlerde mi çalışacağını operasyon ihtiyacına göre seçin.
4. Dış sözleşmeyi iç uygulama yapısından mümkün olduğunca bağımsız tutun.

API sözleşmesi hangi unsurları içermelidir?

API dokümanı yalnızca uç nokta listesinden oluşmamalıdır. İstemcinin başarılı ve başarısız bütün temel senaryolarda ne bekleyeceğini tanımlamalıdır.

• Kaynak ve işlem adları
• HTTP yöntemi ve yol yapısı
• Zorunlu ve isteğe bağlı alanlar
• Veri türleri, formatlar ve sınır değerleri
• Başarılı yanıt örnekleri
• Hata kodu, hata gövdesi ve doğrulama ayrıntıları
• Kimlik doğrulama ve yetkilendirme gereksinimleri
• Sayfalama, filtreleme ve sıralama davranışı
• Idempotency ve tekrar eden istek kuralları
• Sürüm, kullanım dışı bırakma ve değişiklik politikası
• Hız sınırı ve kota bilgileri
• Webhook veya olay bildirimleri

Google’ın API Design Guide’ı, kurum içinde 2014’ten beri kullanılan ve Google Cloud API’lerinin tasarımında izlenen genel bir rehber olarak sunulur Google Cloud API Design Guide. İşletmenin Google standartlarını aynen uygulaması gerekmez; ancak kendi adlandırma, hata, sayfalama ve uyumluluk kurallarını tutarlı biçimde belirlemesi gerekir.

Kaynak ve işlem tasarımı nasıl yapılmalıdır?

API yolları veritabanı tablolarına göre değil, iş dünyasındaki anlaşılır kaynaklara göre tasarlanmalıdır. Müşteri, teklif, sipariş, görev veya servis kaydı gibi kavramlar; ekran adlarından ve iç teknik sınıflardan daha uzun ömürlüdür.

Microsoft’un REST API tasarım rehberi, API’lerin iş varlıklarına odaklanmasını ve HTTP yöntemlerinin bu kaynaklar üzerindeki işlemleri ifade etmesini önerir Microsoft Azure Architecture Center. Yine de her iş süreci standart CRUD işlemine sığmaz. “Siparişi onayla”, “faturayı iptal et” veya “görevi yeniden ata” gibi iş komutları açık ve denetlenebilir operasyonlar olarak modellenebilir.

Tasarım sırasında şu sorular sorulmalıdır:

• Kaynağın değişmeyen kimliği nedir?
• İstemcinin bütün alanları görmesi gerekiyor mu?
• Hangi alanlar yalnızca okunabilir?
• İşlem atomik mi, uzun süren bir görev mi?
• Aynı istek tekrar gelirse ne olur?
• Silme gerçekten fiziksel silme mi, durum değişikliği mi?
• Kaynak hangi kullanıcı, şirket veya tenant sınırında yer alır?

Mock ve sözleşme testleri ne işe yarar?

OpenAPI gibi bir sözleşme üzerinden örnek sunucu oluşturulduğunda istemci ekibi gerçek veriye ihtiyaç duymadan ekran akışlarını geliştirebilir. Ürün sahibi de alan adlarını ve yanıt yapısını kod tamamlanmadan inceleyebilir. Böylece yanlış anlaşılan gereksinim üretim koduna dönüşmeden bulunabilir.

Mock sisteminin gerçek iş davranışını garanti etmediği unutulmamalıdır. Örnek yanıtla çalışan ekran, gerçek sistemde yetki, veri hacmi veya işlem sırası nedeniyle hata verebilir. Bu nedenle sözleşme testleri, uygulamanın yayımlanan şemaya uygun yanıt verip vermediğini; entegrasyon testleri ise gerçek bileşenlerin birlikte doğru sonuç üretip üretmediğini kontrol etmelidir.

Yönetim paneli, mobil uygulama ve harici entegrasyonlar aynı API’yi kullanıyorsa sözleşme değişiklikleri her tüketicinin test paketinde doğrulanmalıdır.

Geriye uyumluluk ve API sürümleme nasıl yönetilir?

API yayımlandıktan sonra tüketiciler bu sözleşmeye bağımlı hâle gelir. Zorunlu alan eklemek, alan türünü değiştirmek, değeri kaldırmak veya mevcut davranışı farklılaştırmak çalışan entegrasyonları bozabilir. Bu nedenle her değişiklikte “sunucu çalışıyor mu?” sorusunun yanında “mevcut istemciler çalışmaya devam ediyor mu?” sorusu sorulmalıdır.

Google’ın geriye uyumluluk rehberi, hangi değişikliklerin uyumlu veya uyumsuz sayılacağını tanımlar ve mevcut istemcileri bozabilecek değişikliklerin dikkatle yönetilmesini vurgular Google AIP-180 Backwards Compatibility. Yeni isteğe bağlı alan eklemek çoğu istemci için uyumlu olabilir; mevcut alanı kaldırmak veya anlamını değiştirmek ise yeni sürüm gerektirebilir.

Gerçek bir kamusal örnek olarak GitHub REST API, tarih tabanlı sürümler kullanır ve yeni sürüm yayımlandığında önceki sürümü en az 24 ay daha destekleyeceğini belirtir GitHub API Versions. Her işletmenin 24 aylık politika uygulaması gerekmez; ancak sürüm adı, destek süresi, geçiş takvimi ve kullanım dışı bırakma bildirimi açık olmalıdır.

Idempotency neden API sözleşmesinin parçası olmalıdır?

Mobil bağlantı kesildiğinde veya istemci zaman aşımı aldığında aynı işlem tekrar gönderilebilir. İlk istek sunucuda tamamlanmış fakat yanıt istemciye ulaşmamışsa ikinci istek mükerrer sipariş, ödeme veya rezervasyon oluşturabilir.

Idempotency anahtarı, aynı mantıksal işlemin tekrar gönderildiğini sunucunun tanımasına yardımcı olur. Stripe API, bağlantı hatası sonrasında isteğin ikinci kez aynı işlemi oluşturmadan güvenli biçimde tekrar edilebilmesi için idempotency key kullanımını destekler Stripe API Reference.

API-first tasarımda hangi işlemlerin idempotent olduğu, anahtarın kapsamı, saklama süresi ve aynı anahtarla farklı veri geldiğinde üretilecek hata sözleşmede tanımlanmalıdır. Bu konu yalnızca ödeme sistemlerine özgü değildir; sipariş, görev, fatura ve rezervasyon gibi yazma işlemlerinde de önemlidir.

Senkron API ile olay tabanlı yapı nasıl birlikte kullanılabilir?

Kullanıcının anında sonuç beklediği sorgu ve işlemler için senkron HTTP API uygundur. Bir sipariş oluşturulduktan sonra bildirim, muhasebe aktarımı veya depo görevi gibi sonraki işlemler olay üzerinden yürütülebilir. Böylece ana işlem bütün dış sistemleri beklemek zorunda kalmaz.

Olay sözleşmeleri de en az HTTP API kadar açık olmalıdır. Olay adı, yayınlanma koşulu, veri şeması, benzersiz kimlik, tekrar davranışı ve sürüm politikası tanımlanmalıdır. AsyncAPI Specification, mesaj tabanlı API’leri protokolden bağımsız ve makine tarafından okunabilir biçimde tanımlamayı amaçlar AsyncAPI Specification.

Her işlemi olaya dönüştürmek gerekmez. Kullanıcı “müşteri bilgilerini getir” dediğinde doğrudan yanıt bekler. “Sipariş oluşturuldu” bilgisi ise birden fazla sistemin daha sonra işleyebileceği olay olabilir. Seçim, iş sonucunun ne kadar sürede gerekli olduğuna ve bileşenlerin birbirinden ne ölçüde bağımsız çalışması gerektiğine göre yapılmalıdır.

API güvenliği tasarım aşamasında nasıl ele alınmalıdır?

API’nin kimlik doğrulama kullanması, her kaydın güvenli olduğu anlamına gelmez. Kullanıcı geçerli token ile giriş yapmış olsa bile başka müşterinin sipariş kimliğini göndererek kayda erişmeye çalışabilir. Her işlemde kaynak, alan ve fonksiyon seviyesinde yetki kontrolü gerekir.

OWASP API Security Top 10 2023 listesinde Broken Object Level Authorization, Broken Authentication ve Broken Object Property Level Authorization ilk sıralarda yer alır OWASP API Security Project. Bu riskler, güvenliğin yalnızca API gateway veya giriş ekranında çözülemeyeceğini gösterir.

API sözleşmesi ve uygulamasında şu kontroller planlanmalıdır:

• Kullanıcı, servis hesabı ve iş ortağı kimliklerinin ayrılması
• Her kaynakta şirket, tenant, rol ve kayıt kapsamı kontrolü
• İstemcinin değiştirmemesi gereken alanların reddedilmesi
• Hız sınırı, kota ve anormal kullanım tespiti
• Hassas verinin gereksiz yanıt alanlarından çıkarılması
• Gizli anahtarların düzenli yenilenmesi ve iptal edilebilmesi
• Yüksek riskli işlemlerin ayrıntılı biçimde loglanması
• Eski ve kullanılmayan API sürümlerinin kapatılması

API yönetişimi ne zaman gerekli olur?

Tek ekip ve birkaç uç noktadan oluşan projede basit kod incelemesi yeterli olabilir. Ekip, modül ve entegrasyon sayısı arttığında aynı kavram farklı adlarla sunulmaya, hata biçimleri ayrışmaya ve dokümantasyon güncelliğini kaybetmeye başlar. Bu noktada API yönetişimi gereklidir.

Yönetişim ağır bir kurul veya uzun onay süreci olmak zorunda değildir. Aşağıdaki mekanizmalar yeterli bir başlangıç oluşturabilir:

• Ortak adlandırma ve veri formatı rehberi
• Standart hata gövdesi ve korelasyon kimliği
• OpenAPI dosyası için kod incelemesi
• Otomatik sözleşme doğrulama ve lint kuralları
• API sahibi ve tüketici listesinin tutulması
• Sürüm ve kullanım dışı bırakma politikası
• Değişiklik günlüğü ve tüketici bildirimi
• Test, güvenlik ve izleme için yayın kalite kapıları

Kurallar geliştiriciyi yavaşlatmak için değil, her ekibin aynı kararları yeniden tartışmasını ve tüketicilerin beklenmedik davranışlarla karşılaşmasını azaltmak için kullanılmalıdır.

API-first yaklaşımı hangi projeler için uygundur?

API-first seçimi moda veya teknoloji tercihi değildir. Projenin kaç tüketicisi olacağı, entegrasyon beklentisi, ekip yapısı ve ürünün planlanan ömrü değerlendirilmelidir.

Gerçekçi bir API-first özel yazılım senaryosu

Varsayımsal olarak teknik servis firmalarına yönelik özel bir platform geliştirildiğini düşünelim. İlk fazda operasyon ekibi web panelinden müşteri, cihaz, iş emri ve teknisyen planı yönetecek; ikinci fazda teknisyenler için mobil uygulama, sonraki aşamada müşteriler için talep portalı hazırlanacak olsun.

API-first çalışmada önce müşteri, cihaz, iş emri, atama ve servis sonucu kaynakları tanımlanır. Her işlem için yetki, zorunlu alan, hata yanıtı ve durum geçişi OpenAPI sözleşmesinde açıklanır. Web ekibi mock API ile paneli geliştirirken arka uç ekibi gerçek davranışı uygular.

Mobil uygulama eklendiğinde iş emri oluşturma mantığı yeniden yazılmaz; mobil yalnızca kendi rolünün erişebildiği uç noktaları kullanır. İş kapatma isteği bağlantı kesintisinde tekrar gelebileceği için idempotency anahtarıyla korunur. İş emri tamamlandığında faturalama ve müşteri bildirimi için olay yayımlanır.

Daha sonra dış bir müşteri portalı açıldığında iç yönetici API’sinin tamamı paylaşılmaz. Aynı iş alanı üzerinde müşteriye özel dar kapsamlı kaynaklar ve yetkiler sunulur. Bu senaryo gerçek bir firma veya performans iddiası değildir; API-first planlamanın kanallar arasında nasıl değer üretebileceğini göstermek amacıyla hazırlanmıştır.

API-first proje başlangıç kontrol listesi

• API’nin tüketicileri web, mobil, iş ortağı ve servis hesabı olarak listelendi mi?
• İş alanları ve her verinin sahibi belirlendi mi?
• API kaynakları ekran veya tablo adlarına değil, iş kavramlarına göre tasarlandı mı?
• İstek, yanıt, hata ve yetki kuralları sözleşmede yer alıyor mu?
• OpenAPI veya uygun başka bir makine okunabilir tanım kullanılıyor mu?
• İstemci ekipleri mock veriyle paralel çalışabiliyor mu?
• Sözleşme ile gerçek uygulama otomatik testlerle karşılaştırılıyor mu?
• Geriye uyumluluk ve sürümleme politikası yazılı mı?
• Idempotency gerektiren yazma işlemleri belirlendi mi?
• Senkron işlemler ile olay tabanlı akışlar ayrıldı mı?
• Kaynak ve alan seviyesinde yetki kontrolleri planlandı mı?
• Hız sınırı, kota, loglama ve izleme gereksinimleri belli mi?
• API sahibi, tüketicileri ve kullanım dışı bırakma süreci tanımlı mı?
• İlk fazda gerçekten kullanılmayacak uç noktalar gereksiz yere tasarlanıyor mu?
• Sözleşme değişiklikleri özel web yazılımı yol haritasıyla birlikte yönetiliyor mu?

Sonuç: API-first, gelecekteki bağlantıları bugünden kodlamak değildir

API-first yaklaşımı, ileride ihtiyaç duyulabilecek her entegrasyonu ilk günden geliştirmek anlamına gelmez. Amaç; yazılımın temel iş yeteneklerini açık sözleşmelerle tanımlamak, mevcut kanalların aynı kuralları kullanmasını sağlamak ve yeni tüketiciler eklendiğinde iç sistemi kontrolsüz biçimde açmamaktır.

Doğru kapsamda uygulandığında API-first; ekiplerin paralel çalışmasına, mobil ve web deneyimlerinin tutarlı kalmasına, sürüm değişikliklerinin yönetilmesine ve iş ortaklarına güvenli erişim sunulmasına yardımcı olur. Küçük projelerde sade tutulmalı; çok kanallı ve uzun ömürlü ürünlerde ise test, güvenlik ve yönetişimle birlikte temel mimari karar olarak ele alınmalıdır.