Entegrasyonlar ihtiyaç doğdukça tek tek kurulduğunda tablo şöyle oluşur: CRM ile ERP arasına bir aktarım betiği yazılır, depo sistemi muhasebeye her gece bir dosya bırakır, mobil uygulama için ayrı bir servis açılır. Her…
Entegrasyonlar ihtiyaç doğdukça tek tek kurulduğunda tablo şöyle oluşur: CRM ile ERP arasına bir aktarım betiği yazılır, depo sistemi muhasebeye her gece bir dosya bırakır, mobil uygulama için ayrı bir servis açılır. Her bağlantı kurulduğu gün mantıklıdır. Birkaç yıl sonra ise hangi sistemin hangisine hangi veriyi, hangi biçimde gönderdiğinin haritasını çıkarmak başlı başına bir iş haline gelir.
API-First yaklaşımda, bu yığına yeni bir bağlantı eklenmeden önce verinin hangi sözleşmeyle paylaşılacağına karar verilir. Sözleşme koddan önce tasarlanır, onu kullanacak ekiplerle birlikte incelenir ve makinelerin okuyabildiği bir dosyada tutulur. Kod bu sözleşmeye göre yazılır ve ona uyup uymadığı otomatik olarak test edilir.
On sistemin her biri diğerleriyle doğrudan konuşabiliyorsa 45 olası sistem çifti oluşur. Her çift arasındaki bağlantının kendi veri biçimi, hata davranışı ve bakım sorumlusu olur. Asıl sorun, bu bağlantıların hiçbirinin bir yerde tanımlı olmamasıdır. Müşteri adresi CRM'de tek alanda, ERP'de beş alanda, e-ticaret sisteminde serbest metin olarak tutuluyorsa, her betik bu farkı kendi yöntemiyle çevirir ve çeviri kuralı yalnızca o betiğin kodunda yaşar. Bir sistemde yapılan küçük bir alan değişikliği, o alanı okuyan ve kimsenin hatırlamadığı bir raporu sessizce bozabilir.
Code-first yaklaşımda önce uygulama yazılır, API dokümantasyonu sonradan koddan üretilir. Bu durumda API'nin şeklini uygulamanın iç veri yapısı belirler; tablo adları, iç durum kodları ve geçici alanlar dış dünyaya sızabilir. Dokümantasyon doğru olsa bile tasarım kararları kod yazılırken, tüketicilere sorulmadan verilmiş olur.
API-First'te aynı kararlar kod yazılmadan önce verilir. Henüz hiçbir tüketici yokken bir alanın adını ya da türünü değiştirmek kimseyi etkilemez, aynı değişiklik canlıya çıktıktan sonra yapıldığında ise her tüketici için ayrı bir uyarlama işi doğurur. Bu sözleşmeler HTTP API'lerde OpenAPI, Event-Driven akışlarda AsyncAPI gibi açık standartlarla yazılır. Sözleşme bu dosyalarda tutulduğunda dokümantasyon, mock uç nokta ve istemci kodu aynı kaynaktan üretilebilir.
Bir API sözleşmesi, tüketen ekibin sağlayıcıya soru sormadan entegrasyonu tamamlayabileceği kadar açık olmalıdır. Bunun için birkaç kararın sözleşme yazılırken netleşmesi gerekir.
İlki veri sahipliğidir. Müşteri kaydının asıl kaynağı CRM ise diğer sistemler müşteri verisini CRM'in API'si üzerinden okur; bu karar verilmeden yazılan sözleşmeler, aynı veriyi iki yerde güncelleyen yapıları kalıcılaştırabilir. İkincisi biçim kurallarıdır: alan adlandırma, tarih biçimi (ISO 8601), para birimi gösterimi ve sayfalama bütün API'lerde aynı olduğunda, yeni bir API'yi kullanmaya başlayan ekip biçim farklarıyla uğraşmaz.
Hata modeli de sözleşmenin parçasıdır. Hangi hata koşulunda hangi HTTP durum kodunun döneceği ve hata gövdesinin yapısı sözleşmede yazılı olmalıdır; RFC 9457 (Problem Details for HTTP APIs) bu gövde için ortak bir biçim tanımlar. Kimlik doğrulama ve yetki için de karar gerekir: yetkilendirme için OAuth 2.0, kimlik doğrulama için OpenID Connect gibi standartlar seçilir, her uç noktanın hangi yetkiyle çağrılabileceği ve dakikada kaç isteğin kabul edileceği (rate limiting) tanımlanır. En sık kullanılan senaryolar için de gerçekçi istek ve yanıt örnekleri sözleşmeye eklenir ve sözleşme değiştikçe güncellenir.
Sözleşme bir kez yazılıp bırakılırsa kısa sürede koddan uzaklaşır. Bunu önlemenin yolu sözleşmeyi geliştirme sürecinin içine almaktır. Sözleşme kodla aynı sürüm kontrol deposunda tutulur ve değişiklikleri kod incelemesinden geçer. Taslak aşamasında sözleşmeden bir mock uç nokta üretilir; tüketen ekip gerçek servis hazır olmadan bu uç noktaya karşı geliştirme yapar ve iki ekip birbirini beklemez.
Sağlayıcının sözleşmeye uyumu şema doğrulamasıyla, tüketicilerin beklentileri ise consumer-driven contract testing ile otomatik olarak kontrol edilir. Bu yöntemde her tüketici, API'den beklediği yanıtı test olarak tanımlar; sağlayıcı ekip bir değişiklik yaptığında bu testler sürekli entegrasyon hattında çalışır ve hangi tüketicinin etkileneceğini canlıya çıkmadan gösterir. Pact, bu amaçla yaygın olarak kullanılan araçlardan biridir.
Yanıta isteğe bağlı yeni bir alan eklemek genellikle geriye dönük uyumludur; bir alanı silmek, alanın türünü değiştirmek ya da isteğe zorunlu yeni bir alan eklemek ise uyumu bozar (breaking change). Bu ayrımın sözleşmede ve ekip kurallarında yazılı olması gerekir, çünkü "küçük bir düzeltme" diye yapılan bir alan adı değişikliği bile entegrasyonları kırabilir. Uyumu bozan bir değişiklik kaçınılmazsa yeni bir sürüm yayınlanır, eski sürümün ne kadar süre destekleneceği önceden duyurulur ve tüketiciler bu süre içinde taşınır.
Bir şirketin CRM, ERP ve e-ticaret sistemlerinde müşteri bilgisinin üç farklı biçimde tutulduğunu ve her sistem çifti arasında ayrı bir aktarım betiği çalıştığını düşünelim. API-First yaklaşımla önce tek bir "Customer" kaynağı tasarlanır. Sözleşmede kalıcı müşteri numarasının hangi sistemde üretildiği, adresin hangi alt alanlardan oluştuğu ve hangilerinin zorunlu olduğu, T.C. kimlik numarası ve vergi numarası gibi alanların hangi yetkiyle okunabileceği yazılır.
ERP ve e-ticaret sistemi müşteri verisine artık bu sözleşme üzerinden erişir. Müşteri kaydı değiştiğinde CRM, örneğin CustomerUpdated adlı bir olay yayınlar; olayın sözleşmesi de AsyncAPI ile yazılır ve müşteri numarasını, değişen alanları ve değişikliğin zamanını içerir. ERP ve e-ticaret sistemi bu olayı dinleyerek kendi kopyalarını günceller, sistem çiftleri arasındaki aktarım betiklerine gerek kalmaz. Adres biçimi değiştiğinde değişiklik tek bir sözleşmede yapılır ve sürüm kuralına göre duyurulur.
Her sözleşmenin bir sahibi olmalıdır. Sahip ekip değişiklik taleplerini değerlendirir ve uyumu bozan değişiklikleri tüketicilerle birlikte planlar. Kurumdaki API'lerin sahipleri ve sözleşme dosyalarıyla birlikte tek bir katalogda bulunması, var olan bir API'nin bilinmediği için yeniden yazılması riskini azaltır.
API gateway trafiği yönlendirir, erişim belirteçlerini doğrular ve istekleri sınırlar; kötü tasarlanmış bir sözleşmeyi ise düzeltemez. Kişisel veri içeren uç noktalarda her yanıtın yalnızca tüketicinin kullandığı alanları döndürmesi, KVKK'nın 4. maddesindeki "işlendikleri amaçla bağlantılı, sınırlı ve ölçülü olma" ilkesiyle ve GDPR'nin 5. maddesindeki veri minimizasyonu ilkesiyle örtüşür.
Bütün entegrasyonları bir anda yeniden yazmak gerekmez. İlk aday, çok sistemin bağlı olduğu ve sık sorun çıkaran bir entegrasyon olabilir; sözleşmenin etkisi en açık orada görülür. Bu entegrasyon için sözleşme yazılır, eski bağlantı yeni API'ye taşınır ve aynı adımlar bir sonraki entegrasyonda tekrarlanır. Geçişin ilerleyişi, kalan noktadan noktaya bağlantı sayısından ve duyurulmadan canlıya çıkan uyumu bozan değişikliklerden izlenebilir.