API Sözleşmesi ve OpenAPI: Entegrasyona Koddan Önce Başlamak

Sözleşme, başarılı yanıt örneğinden büyüktür

Bir sipariş oluşturma servisi hangi alanları ister, eksik bilgiye nasıl yanıt verir ve kabul edilen işlem ne zaman tamamlanmış sayılır? Bu davranışlar bütün tüketiciler için aynı anlama gelmelidir. Bir geliştiricinin mesajla paylaştığı örnek JSON, sınırlar ve hatalar açıklanmadığında eksik bir başlangıçtır.

OpenAPI, HTTP API yeteneklerini programlama dilinden bağımsız biçimde tanımlayan bir standarttır; istekler, yanıtlar ve güvenlik şemaları bu tanımın parçaları olabilir. [1] Ancak belgede bir yetki şeması bulunması, çalışan sunucunun bunu gerçekten uyguladığını kanıtlamaz. Belge ve uygulama ayrı doğrulanmalıdır.

Alanın türü kadar anlamını da yazın

“Tutar” alanı sayısal olabilir, fakat vergi dahil mi, hangi para biriminde ve hangi hassasiyetle? “Tarih” teslim tarihi mi, oluşturulma anı mı? Tür doğrulaması bu anlamsal soruları çözmez. Her kritik alan için örnek, birim, zorunluluk ve boş değerin anlamı açıklansın.

Varsayımsal bir sipariş bağlantısında müşteri kodu, mağaza içindeki müşteriyle ERP’deki cariyi eşleştirsin. Bu iki kod aynı değeri taşımıyorsa entegrasyonun eşleştirme kuralı görünür olmalıdır. Kullanıcı ekranda doğru adı görse bile servis yanlış cari kimliğiyle kayıt açabilir. Kabul testi kimlikleri de kapsamalıdır.

Hata sözlüğünü istemcinin davranışına bağlayın

Düzeltilebilir veri hatası, yetki eksikliği ve geçici dış servis sorunu farklı sonuçlardır. İstemci hangisinde kullanıcıdan düzeltme isteyecek, hangisinde tekrar deneyecek? Hata kodu kararlı, açıklama anlaşılır olsun. Sunucu yığını, gizli anahtar veya kişisel kayıtlar hata mesajına eklenmemelidir.

İşlem zaman aşımına uğradığında sonucun belirsiz kalması mümkündür. İstemci aynı isteği tekrar gönderdiğinde yeni kayıt mı oluşacak, önceki sonuç mu bulunacak? İşlem kimliği ve tekrar davranışı sözleşmede açıklansın. “Başarısız” görünen ağ isteğinin iş açısından tamamlanmış olabileceği senaryoyu test edin.

Örnek API kabul matrisi

Bu tablo OpenAPI’nin otomatik sağladığı testler listesi değildir. Projenin davranışını doğrulamak için önerilen senaryolardır. Şema testleriyle iş kuralı testlerini birlikte kullanın. Örneğin sayı alanının kabul edilmesi, sipariş miktarının gerçekten uygun olduğunu göstermez.

Dokümantasyonu sürüm sürecine dahil edin

Sözleşme dosyası koddan bağımsız biçimde unutulmasın. Değişiklik incelemesinde API tanımı, örnekler ve uyumluluk etkisi birlikte değerlendirilsin. Kullanılan araçların desteklediği OpenAPI sürümü kontrol edilmelidir; yalnızca en yeni sürüm numarasını seçmek bütün istemcilerin uyumlu olduğu anlamına gelmez.

Teslimde başka bir ekip yalnızca belgelerle temsilî işlemi yapabilsin. Sorulan her ek açıklama sözleşmede eksik kalan noktayı gösterebilir. Kurulum erişimi, test verisi ve hata örnekleri sağlansın; fakat gerçek müşterinin verisi örnek dosyaya taşınmasın. Entegrasyonun bakım sorumlusu da açıkça belirtilsin.

Sık sorulan sorular

OpenAPI dosyası varsa entegrasyon tamam mı?

Hayır. Tanımla çalışan servisin aynı davranışı göstermesi, yetkilerin uygulanması ve gerçek iş akışının tamamlanması ayrıca test edilmelidir.

Belgeyi koddan üretmek yeterli olur mu?

Yardımcı olabilir, ancak alanların iş anlamı ve istisnalar her zaman otomatik çıkmaz. Üretilen tanımın tüketici ekip tarafından incelenmesi gerekir.