Bir API yayına alındığı anda bir sözleşmeye dönüşür. Mobil uygulama, web paneli, acentenin kendi web sitesi ya da iş ortaklarının sistemleri bu sözleşmeye güvenerek çalışır. Ürün geliştikçe API'nin de değişmesi kaçınılmazdır: Yeni alanlar eklenir, bazı alanların anlamı netleşir, bazı uç noktalar artık gerekli olmaz. Sürümleme, bu değişimin mevcut istemcileri kırmadan yönetilmesini sağlayan disiplindir. Bu yazıda acente yazılımı bağlamında API sürümlemenin pratik yöntemlerini ve sık yapılan hataları ele alıyoruz.
Hangi değişiklikler kırıcıdır?
Sürümleme stratejisine geçmeden önce, hangi değişikliklerin istemcileri etkilediğini netleştirmek gerekir.
Genellikle kırıcı olmayan değişiklikler
- Yanıta yeni ve isteğe bağlı bir alan eklemek
- Yeni bir uç nokta eklemek
- İsteğe yeni bir isteğe bağlı parametre eklemek
Kırıcı değişiklikler
- Bir alanı kaldırmak veya adını değiştirmek
- Bir alanın veri tipini değiştirmek, örneğin sayıyı metne çevirmek
- İsteğe bağlı bir parametreyi zorunlu hale getirmek
- Bir alanın anlamını değiştirmek, örneğin tutarın vergiler dahil yerine vergiler hariç dönmesi
- Hata kodlarının veya durum değerlerinin değişmesi
Son madde özellikle sinsidir. Alan adı ve tipi aynı kaldığı için değişiklik teknik olarak fark edilmez; ama istemci yanlış sonuç gösterir. Anlam değişikliği her zaman kırıcı kabul edilmelidir.
Sürümleme yöntemleri
URL yolunda sürüm
En yaygın ve en anlaşılır yöntemdir. Sürüm numarası adresin bir parçasıdır: /v1/teklifler ve /v2/teklifler gibi. Avantajı, hangi sürümün kullanıldığının loglarda ve tarayıcıda açıkça görünmesidir. Önbellekleme ve yönlendirme kuralları da kolayca yazılır. Dezavantajı, kaynakların kimliğinin sürüme bağlanmasıdır; aynı teklif kaydı iki farklı adreste yaşıyor gibi görünür.
Başlıkta sürüm
Sürüm bilgisi özel bir HTTP başlığında veya içerik türü başlığında taşınır. Adresler sabit kalır, bu yönüyle daha temiz bir tasarımdır. Ancak test ve hata ayıklama sırasında sürümün gözden kaçması kolaydır ve bazı ara katmanlar başlıkları beklenmedik biçimde işleyebilir.
Tarih tabanlı sürüm
Her istemci, entegrasyonu yaptığı tarihe sabitlenir ve API o tarihteki davranışı sunar. Yeni değişiklikler yalnızca daha yeni tarihi seçen istemcilere uygulanır. Bu yöntem çok sayıda küçük değişikliği yönetmek için esnektir ama sunucu tarafında sürümler arası dönüşüm katmanlarının dikkatle bakımını gerektirir.
Hangi yöntem seçilirse seçilsin, en önemli kural tutarlılıktır. Aynı API içinde bazı uç noktaların URL ile, bazılarının başlıkla sürümlenmesi istemci geliştiricileri için kafa karıştırıcıdır.
Sürüm açmadan önce: Genişletilebilir tasarım
En iyi sürümleme stratejisi, yeni sürüme ihtiyacı azaltan bir tasarımdır. Bunun için birkaç ilke işe yarar:
- İstemciler bilinmeyen alanları yok saymalıdır: Bu kural belgelenir ve resmi istemcilerde uygulanırsa yeni alan eklemek hiçbir zaman kırıcı olmaz.
- Durum değerleri genişletilebilir olmalıdır: Bir teklifin durumu için bugün dört değer varsa, istemciler beşinci bir değer geldiğinde çökmemeli, onu bilinmeyen durum olarak göstermelidir.
- Branşlar ayrı kaynaklar olarak modellenmelidir: Trafik, kasko ve DASK sorguları farklı girdi alanlarına sahip olduğundan tek bir ortak teklif şeması yerine branşa özel şemalar tanımlamak, bir branşta yapılan değişikliğin diğerlerini etkilemesini önler.
- Para birimleri ve tutarlar açık tanımlanmalıdır: Tutarın hangi birimde ve hangi kalemleri içerdiği şemada belirtilirse ileride anlam değişikliği riski azalır.
Eski sürümleri emekliye ayırmak
Yeni bir sürüm yayınlamak işin kolay kısmıdır. Asıl zorluk, eski sürümü güvenle kapatmaktır. Sağlıklı bir emeklilik süreci şu adımları içerir:
- Kullanım verisini toplayın: Hangi istemcinin hangi sürümü ne sıklıkla kullandığını bilin. Bu veri olmadan kapatma kararı karanlıkta atılan bir adımdır.
- Kullanımdan kaldırma duyurusu yapın: Değişikliği belgelerde, sürüm notlarında ve ilgili istemcilere doğrudan iletişimle duyurun.
- Yanıtlarda uyarı başlığı gönderin: Eski sürümü kullanan isteklere, sürümün kullanımdan kaldırılacağını ve planlanan tarihi bildiren standart başlıklar eklenebilir.
- Makul bir geçiş süresi tanıyın: Özellikle mobil uygulamalarda kullanıcıların güncellemeyi geciktirebileceği hesaba katılmalıdır.
- Kademeli kapatın: Doğrudan kapatmak yerine önce kısa süreli planlı kesintilerle hâlâ eski sürüme bağlı istemcileri görünür hale getirin.
Mobil uygulamalarda özel durum
Web paneli güncellendiğinde bütün kullanıcılar bir sonraki sayfa yenilemesinde yeni sürüme geçer. Mobil uygulamada ise durum farklıdır; bazı kullanıcılar haftalarca eski sürümü kullanmaya devam edebilir. Bu nedenle mobil istemcilerin kullandığı API sürümleri daha uzun süre desteklenmelidir. Ayrıca uygulama içinde, desteklenmeyen bir sürüm kullanıldığında kullanıcıyı güncellemeye yönlendiren bir mekanizma bulunmalıdır. Bu mekanizma ilk sürümden itibaren uygulamada yer almazsa, sonradan eklemek mümkün olmaz.
Sözleşme testleriyle güvence
Sürümleme kurallarının kâğıt üzerinde kalmaması için her yayın öncesinde API şemasının bir önceki sürümle otomatik olarak karşılaştırılması önerilir. Bu karşılaştırma, kaldırılan alanları, değişen tipleri ve zorunlu hale gelen parametreleri tespit eder. Kırıcı bir değişiklik bulunduğunda yayın durdurulur ve ya yeni sürüm açılır ya da değişiklik geriye uyumlu hale getirilir.
Dokümantasyon ve değişiklik günlüğü
Sürümleme stratejisi, ancak istemci geliştiricileri tarafından anlaşıldığında işe yarar. Her sürüm için güncel bir başvuru dokümanı, sürümler arasındaki farkları özetleyen bir geçiş rehberi ve tarih sıralı bir değişiklik günlüğü tutulmalıdır. Değişiklik günlüğünde her kaydın kırıcı olup olmadığı açıkça işaretlenmelidir. Geçiş rehberinde ise eski istek ve yanıt örneklerinin yeni karşılıklarıyla yan yana gösterilmesi, entegrasyonu güncelleyecek ekibin işini belirgin biçimde kolaylaştırır.
Dokümanların kod ile senkron kalması için API şemasından otomatik üretilmesi tercih edilmelidir. Elle güncellenen belgeler zamanla gerçeği yansıtmaz hale gelir ve en kritik anda, yani bir istemci eski sürümden yeni sürüme geçerken yanıltıcı olur.
InsureHub açısından
InsureHub, sigorta acentelerine yazılım sağlarken web paneli, mobil sigorta uygulaması ve teklif motoru arasındaki iletişimi sürümlü API'ler üzerinden yürütmeyi benimser. Uzun süren işlemler için sürümlenmiş motor API'leri, mobil istemcilerin güncelleme takvimine uyum sağlarken sigorta acentesi yazılımı tarafındaki yeniliklerin de kesintisiz yayına alınmasına yardımcı olur.