API Versiyonlama Stratejileri: Kırıcı Değişiklikleri Sancısız Yönetmek

Bir API yayına alındığı andan itibaren, onu kullanan sistemlerle sessiz bir sözleşme imzalamış olursunuz: "Ben böyle çalışacağım, sen de buna güvenerek kod yazabilirsin." Ancak zamanla ihtiyaçlar değişir, yeni alanlar eklemek, veri yapısını sadeleştirmek ya da yanlış tasarlanmış bir uç noktayı düzeltmek gerekir. İşte tam bu noktada versiyonlama devreye girer; çünkü bu sözleşmeyi bozmadan onu geliştirmenin tek yolu, değişikliği kontrollü bir şekilde sürümlere ayırmaktır.

Neden Versiyonlamaya İhtiyaç Var?

Bir API'de yapılan her değişiklik iki gruba ayrılır: geriye dönük uyumlu (backward compatible) olanlar ve kırıcı (breaking) olanlar. Yeni bir isteğe bağlı alan eklemek genellikle uyumludur; mevcut istemciler bundan etkilenmez. Ancak bir alanı silmek, bir alanın adını değiştirmek, veri tipini dönüştürmek ya da bir uç noktanın davranışını değiştirmek kırıcıdır. Kırıcı bir değişiklik, o API'ye bağlı entegrasyonların bir gün aniden çalışmayı bırakması demektir.

Versiyonlama, bir API'yi ilerletirken geriye bağlı sistemlerin altındaki zemini çekmemektir. Değişimi yasaklamaz; onu güvenli hale getirir.

Özellikle üçüncü partilerin kullandığı bir API'de, karşı tarafın ne zaman güncelleme yapacağını kontrol edemezsiniz. Bir ödeme sağlayıcısı ya da kargo firmasının yazılımı, sizin API'nize belirli bir formatta güvenerek bağlanmıştır. Onları önceden haberdar etmeden yapılan bir değişiklik, canlı sistemlerde kesintiye yol açar.

Başlıca Versiyonlama Yöntemleri

Versiyonlamanın birkaç yaygın yaklaşımı vardır; her birinin avantajı ve dezavantajı bulunur.

1. URL Tabanlı Versiyonlama

En yaygın ve en görünür yöntemdir. Sürüm, doğrudan yolun içinde yer alır:

GET /v1/orders/1024
GET /v2/orders/1024

Avantajı, son derece açık olmasıdır; bir bağlantıya bakan herkes hangi sürümü kullandığını görür. Test etmek ve tarayıcıdan denemek kolaydır. Dezavantajı ise teorik olarak REST saflığına aykırı olmasıdır; çünkü aynı kaynak (sipariş 1024) farklı URL'lerle temsil edilir. Pratikte bu tartışma çoğu ekip için ikincil kalır; URL tabanlı versiyonlama sadeliği nedeniyle en çok tercih edilen yöntemdir.

2. Başlık (Header) Tabanlı Versiyonlama

Sürüm bilgisi, özel bir HTTP başlığında taşınır:

GET /orders/1024
X-API-Version: 2

Bu yöntem URL'i temiz tutar ve aynı kaynağın tek bir adresi olur. Ancak tarayıcıdan test etmek zorlaşır ve başlığın unutulması durumunda hangi sürümün varsayılacağı net tanımlanmalıdır.

3. Medya Tipi (İçerik) Tabanlı Versiyonlama

En "REST'e uygun" kabul edilen yöntemdir. Sürüm, Accept başlığında medya tipiyle birlikte belirtilir:

Accept: application/vnd.berasoft.v2+json

Bu yaklaşım güçlüdür ancak karmaşıktır; küçük ve orta ölçekli projelerde çoğu zaman gereğinden fazla yük getirir.

Kırıcı Değişiklikleri Yönetmek

Doğru versiyonlama yöntemini seçmek işin yarısıdır; asıl mesele değişikliği nasıl duyurup yönettiğinizdir. Sağlıklı bir geçiş süreci şu adımları içerir:

1. Yeni sürümü yayınlayın ama eski sürümü hemen kapatmayın.
2. Kullanım dışı bırakma (deprecation) bildirimi yapın; yanıt başlıklarında ya da dokümantasyonda eski sürümün ne zaman kapanacağını açıkça belirtin.
3. Geçiş süresi tanıyın; istemcilerin yeni sürüme uyum sağlaması için makul bir zaman verin.
4. İzleme yapın; eski sürümü kimin hâlâ kullandığını takip edin ve doğrudan bilgilendirin.
5. Son tarihte kapatın ve net bir hata mesajıyla yeni sürüme yönlendirin.

Bir API sürümünü kapatmak, bir binayı yıkmaya benzer: önce içindeki herkesi tahliye ettiğinizden emin olmanız gerekir.

Kaç Sürüm Aynı Anda Yaşamalı?

Sonsuz sayıda sürümü canlı tutmak, bakım maliyetini katlar. Her sürüm ayrı bir kod yolu, ayrı test, ayrı güvenlik yaması demektir. Pratik yaklaşım, en fazla iki sürümü (mevcut ve bir önceki) aktif tutmak, üçüncü bir sürüm çıktığında en eskisini kademeli olarak emekliye ayırmaktır. Bu denge, hem esnekliği hem de yönetilebilirliği korur.

• Yalnızca uyumlu değişiklikler yapıyorsanız yeni sürüme gerek yoktur.
• Kırıcı bir değişiklik zorunluysa yeni bir majör sürüm açın.
• Eski sürümü kapatmadan önce mutlaka kullanım verisine bakın.

Berasoft Yaklaşımı

Özel yazılım projelerinde API'yi baştan sürümlenebilir tasarlamak, ileride yaşanacak birçok sancıyı önler. Çoğu zaman ilk sürümde /v1 önekiyle başlamak ve değişiklik günlüğü (changelog) tutmak yeterlidir. Kurumsal entegrasyonlarda ise geçiş planını müşterinin partnerleriyle birlikte kurgulamak gerekir. Böyle bir yol haritasını birlikte çıkarmak isterseniz bizimle iletişime geçebilirsiniz.

Sonuç

Versiyonlama, bir API'nin olgunluğunun göstergesidir. İyi versiyonlanmış bir API değişebilir, gelişebilir ve büyüyebilir; ama bunu yaparken kimseyi ortada bırakmaz. URL tabanlı yöntemin sadeliği çoğu projeye yeter; asıl fark, değişikliği ne kadar şeffaf ve planlı duyurduğunuzda ortaya çıkar. Kırıcı değişiklikleri kaçınılmaz kabul edip onları kontrollü bir sürece bağladığınızda, hem sizin hem de API'nize güvenen sistemlerin hayatı kolaylaşır.