API tasarımında sözleşme ve geriye dönük uyumluluk

Kurumsal entegrasyonda API sözleşmesi neden stratejik?

API’ler artık yalnızca teknik arayüz değil; tedarikçiler, bayiler, iç ekipler ve mobil kanallar arasındaki iş sözleşmesinin dijital ifadesidir. Alan adları, hata kodları, sayfalama kuralları ve versiyonlama politikası değiştiğinde entegrasyon partnerleri haftalarca uyum çalışması yapabilir. Net bir sözleşme, proje takvimini ve destek maliyetini doğrudan etkiler.

Aksiyon Soft’ta kurumsal yazılım çözümleri ve entegrasyon katmanları tasarlarken “tüketici beklentisi”ni erken yazıya dökeriz: hangi alanlar zorunlu, hangi hatalar yeniden denenebilir, hangi alanlar deprecated olacak.

• • •

Sözleşmenin bileşenleri

İyi bir kurumsal API sözleşmesi dört katmanda okunabilir olmalıdır:

• Veri modeli: alan tipleri, zorunluluk, enum değerleri, tarih/saat formatı
• Davranış: idempotency, sıralama, filtre limitleri, rate limit mesajları
• Hata modeli: makine okunur kod + insan okunur mesaj + correlation id
• Yaşam döngüsü: sürüm numarası, sunset tarihi, migration rehberi

OpenAPI veya benzeri şema tek başına yeterli değildir; “iş kuralı” notları (ör. indirim hesabının hangi durumda uygulanmayacağı) partner dokümantasyonunda yer almalıdır. Çözümler sayfamızdaki entegrasyon örnekleri bu bütünlüğü hedefler.

Geriye dönük uyumluluk: ekle, kırma

Kurumsal ortamlarda “big bang” API değişikliği nadiren kabul görür. Pratik kural: eklemeler geriye uyumludur, kaldırmalar ve anlam değişiklikleri yeni sürüm gerektirir. Alan silmek yerine deprecated işaretleyin; en az bir release döngüsü uyarı verin; kullanım metrikleri ile gerçekten tüketilip tüketilmediğini ölçün.

Versiyonlama stratejisini (URL path, header veya içerik müzakere) proje başında seçin ve değiştirmeyin. Karışık modeller destek yükünü katlar.

• • •

Hata sözleşmesi ve operasyon

Tüketici ekipler HTTP 500 gördüğünde ne yapacak? Retry mı, destek mi, manuel telafi mi? Hata gövdesinde tutarlı bir code alanı ve requestId sunmak, hem gözlemlenebilirlik hem de müşteri destek süreçlerini hızlandırır.

4xx ve 5xx ayrımını iş dilinde anlatın: 4xx genelde istemci düzeltmesi, 5xx sağlayıcı müdahalesi. Rate limit yanıtlarında Retry-After veya eşdeğeri net olsun.

Test, sandbox ve sözleşme doğrulama

Kurumsal API programlarında sandbox ortamı “nice to have” değildir. Partner ekipler üretime geçmeden önce negatif senaryoları (eksik alan, çakışan id, yetkisiz rol) denemelidir. Contract testleri CI’da çalıştığında sürüm kaymaları erken yakalanır.

• Örnek istek/yanıt setleri her sürümle birlikte yayınlanır
• Breaking change PR’ları changelog’da vurgulanır
• Deprecated uçlar için kullanım grafiği paylaşılır

Güvenlik ve yetkilendirme sözleşmeye dahil

OAuth scope’ları, API anahtarı rotasyonu ve IP kısıtları dokümante edilmeli. Yetkilendirme modeli RBAC tasarımı ile uyumlu olduğunda entegrasyon ekipleri “hangi rol hangi uç noktayı çağırır” sorusunu net yanıtlar.

Güvenlik değerlendirmesi öncesi kontrol listemiz API yüzeyini de kapsar: kimlik doğrulama zorunluluğu, loglarda gizli veri, bağımlılık güncellemeleri.

Paydaş iletişimi ve sürüm notları

Teknik ekip sürüm notu yazarken iş birimi “müşteriye ne söyleyeceğiz?” sorusunu da yanıtlamalı. Aksiyon Soft platform müşterilerinde düzenli sürüm iletişimi için platform güncellemeleri yaklaşımımızı örnek alabilirsiniz: önceden duyuru, migration penceresi, geri dönüş planı.

Özel yazılım geliştirme projelerinde API sahipliği (product owner + teknik lead) sözleşme güncellemelerinin gecikmemesini sağlar.

Tüketici ekiplerle ilişki yönetimi

Kurumsal API programlarında teknik kalite kadar ilişki de sözleşmenin parçasıdır. Partner ekiplerin sandbox erişimi, test hesapları ve destek hattı net olmalıdır. Breaking change duyurusu yalnızca e-posta değil; changelog, webhook veya durum kanalı ile tekrarlanmalıdır. “Sessiz” alan kaldırma, güveni kalıcı zedeler.

İç tüketiciler (mobil ekip, BI, RPA) dış partnerler kadar formal olmayabilir; yine de aynı sürüm politikasına tabi tutulmalıdır. Aksi halde iç entegrasyonlar üretimde kırılır ve dış müşteriye yansıyan kesintiler oluşur.

Sözleşme olgunluk seviyeleri

Seviye 1: OpenAPI şema ve örnek istekler. Seviye 2: hata kodu sözlüğü ve rate limit politikası. Seviye 3: deprecation takvimi, kullanım metrikleri paylaşımı ve migration rehberleri. Seviye 4: otomatik contract test, sandbox SLA ve sürüm önizleme ortamı. Kurumsal entegrasyon sayısı arttıkça seviye 3–4’e geçiş maliyetten tasarruf sağlar.

Regülasyon gerektiren sektörlerde (finans, sağlık, kamu) API değişiklikleri denetim izi bırakmalıdır: kim onayladı, hangi tüketiciler bilgilendirildi, hangi tarihte sunset uygulandı. Bu kayıtlar çözüm mimarisinin audit modülü ile de desteklenebilir.

Entegrasyon projelerinde sözleşme atölyesi

Keşif sonunda yarım günlük “API sözleşme atölyesi” yapın: tüketici ve sağlayıcı ekipler aynı masada örnek JSON gövdelerini ve hata senaryolarını doldurur. Atölye çıktısı doğrudan OpenAPI ve partner portalına gider. Bu adım, sprint ortasında “alan adı ne olsun?” tartışmalarını %50’ye kadar azaltabilir.

Sözleşmede “bilinmeyen alanlar yok sayılır” mı yoksa “reddedilir” mi kuralı açık yazılmalıdır. Kurumsal sistemlerde katı reddetme entegrasyonu erken hata verir ama veri kalitesini korur; yok sayma geçici uyumluluk sağlar ama sessiz veri bozulması riski taşır. İş kararıdır, varsayılan bırakılmamalıdır.

Webhook ve olay tabanlı entegrasyonlarda sıra numarası, tekrar teslimat (at-least-once) ve idempotency anahtarı sözleşmenin ayrı bölümünde yer almalıdır. Pull API ile aynı hata modelini paylaşmaları destek maliyetini düşürür.

Sözleşme ihlali durumunda (ör. beklenmeyen alan tipi) istemci ve sunucu logları aynı correlation id ile eşleşebilmeli; bu id partner dokümantasyonunda “destek talebinde iletin” diye vurgulanmalıdır.

Özet kontrol listesi

• Şema + iş kuralı dokümantasyonu tek yerde mi?
• Breaking change tanımı ekipçe paylaşıldı mı?
• Hata gövdesi correlation id içeriyor mu?
• Sandbox negatif test senaryoları mevcut mu?
• Sunset tarihleri tüketicilere iletildi mi?

Ölçüm: entegrasyon sağlığı

API sahipleri aylık olarak hata oranı, p95 gecikme, deprecated uç kullanımı ve rate-limit isabetlerini tüketicilerle paylaşan kısa rapor yayımlamalıdır. Şeffaf metrik, “sistem yavaş” şikayetlerini objektif veriye taşır ve sürüm kararlarını hızlandırır.

API sözleşmesini canlıda tek kaynak (single source of truth) olarak tutun; e-posta ekleri ve sohbet kararları resmi sürüm notuna taşınmadıkça geçersiz sayılmalıdır.

Özet

Kurumsal API tasarımı, uzun ömürlü entegrasyon ilişkileri için sözleşme disiplini gerektirir. Geriye dönük uyumluluk, tutarlı hata modeli ve şeffaf sürüm iletişimi; proje riskini ve operasyon maliyetini düşürür. Entegrasyon yol haritanızı birlikte netleştirmek için iletişim formunu kullanın. Mevcut OpenAPI veya partner dokümanlarınızı keşif talebiyle birlikte iletmeniz sözleşme atölyesini hızlandırır.