Mobil uygulamalar için API sürümlendirme: uç noktaları güvenle evrimleştirin

Neden API değişiklikleri mobil kullanıcıları bozar

Mobil uygulamalar aynı anda güncellenmez. Bugün bir düzeltme yayınlasanız bile, birçok kişi eski bir sürümü günler veya haftalar boyunca kullanmaya devam eder. Bazıları otomatik güncellemeleri kapatır. Bazıları depolama alanı sıkıntısı yaşar. Bazıları uygulamayı nadiren açar. Mağaza inceleme süresi ve kademeli yayınlar daha fazla gecikme ekler.

Bu fark önemlidir çünkü backend genellikle mobil istemcilerden daha hızlı değişir. Sunucu bir uç noktayı değiştirirse ve eski uygulama hala onu çağırıyorsa, kullanıcıların telefonunda hiçbir şey değişmemiş olsa bile uygulama bozulabilir.

Kırılma nadiren net bir hata mesajı olarak görünür. Genellikle günlük ürün ağrısı olarak ortaya çıkar:

• Backend yayını sonrası giriş veya kayıt başarısız olur
• Bir alan yeniden adlandırıldığı veya taşındığı için listeler boş görünür
• Uygulama eksik bir değeri okurken çöker
• Doğrulama sıkılaştığı için ödemeler başarısız olur
• Yanıt biçimi değiştiği için özellikler sessizce kaybolur

Sürümlemenin amacı basit: herkesi hemen güncellemeye zorlamadan sunucu iyileştirmeleri göndermeye devam etmek. API'nizi uzun süreli bir sözleşme gibi ele alın. Yeni uygulama sürümleri yeni sunucu davranışıyla çalışmalı; eski sürümler ise gerçek dünya güncelleme döngüleri için yeterince uzun süre çalışmaya devam etmelidir.

Çoğu tüketici uygulaması için aynı anda birden fazla uygulama sürümünü desteklemeyi bekleyin. Dahili uygulamalar bazen daha hızlı hareket edebilir, ama yine de nadiren anında olur. Çakışma planlamak, kademeli yayınları sakin tutar; aksi takdirde her backend yayını bir destek krizine dönüşebilir.

Bir API sözleşmesi için “uyumlu” ne demek

API sözleşmesi, mobil uygulamanız ile sunucunuz arasındaki vaat: hangi URL çağrılır, hangi girdiler kabul edilir, yanıt nasıl görünür ve her alan ne anlama gelir. Uygulama bu vaade güveniyorsa ve sunucu bunu değiştirirse kullanıcılar bunu çökme, eksik veri veya çalışmayan özellikler olarak hisseder.

Bir değişiklik, eski uygulama sürümlerinin kod değişikliği olmadan API'yi kullanmaya devam edebilmesiyse uyumludur. Pratikte bu, sunucunun eski uygulamaların gönderdiğini hala anlaması ve eski uygulamaların ayrıştırabileceği yanıtlar döndürmesi demektir.

Güvenli değişiklikleri risklilerden ayırmanın hızlı bir yolu:

• Kırıcı değişiklikler: bir alanı kaldırmak veya yeniden adlandırmak, tür değiştirmek (sayıdan string'e), isteğe bağlı bir alanı zorunlu yapmak, hata formatını değiştirmek, eski uygulamaların karşılayamadığı şekilde doğrulamayı sıkılaştırmak.
• Genellikle güvenli değişiklikler: yeni isteğe bağlı bir alan eklemek, yeni bir uç nokta eklemek, hem eski hem yeni istek formatlarını kabul etmek, yeni enum değerleri eklemek (yalnızca uygulama bilinmeyen değerleri “diğer” olarak ele alıyorsa).

Uyumluluk aynı zamanda bir ömür sonu planı gerektirir. Eski davranışı emekliye ayırmak sorun değil, ama bunun planlı olması gerekir (örneğin, “v2 yayınlandıktan sonra v1'i 90 gün tut”) ki evrim kullanıcıları şaşırtmasın.

Yaygın sürümlendirme yaklaşımları ve ödünleşimler

Sürümlendirme, eski build'lere stabil bir sözleşme verirken ileriye doğru hareket etmektir. Bazı yaygın yaklaşımlar vardır ve her biri karmaşıklığı farklı bir yere koyar.

URL sürümlendirme

Versiyonu yolu içinde koymak (ör. /v1/ ve /v2/) görmek ve hata ayıklamak için en kolay yoldur. Ayrıca versiyon URL'nin bir parçası olduğu için cache, logging ve routing ile iyi çalışır. Dezavantajı, fark küçük olsa bile ekiplerin beklenenden daha uzun süre paralel handler'lar sürdürmesine yol açabilmesidir.

Header tabanlı sürümlendirme

Header sürümlendirmede, istemci bir başlıkta sürümü gönderir (örneğin bir Accept başlığı veya özel bir başlık). URL'ler temiz kalır ve her yolu değiştirmeden API'yi geliştirebilirsiniz. Dezavantajı görünürlük: proxy'ler, loglar ve insanlar sürümü kaçırabilir; mobil istemcilerin her istekte başlığı güvenilir şekilde ayarlaması gerekir.

Sorgu parametresiyle sürümlendirme

Sorgu sürümlendirmesi (ör. ?v=2) basit görünür ama karmaşıklaşır. Parametreler yer imlerine, analiz araçlarına ve script'lere kopyalanır ve sahipliği belli olmayan birden fazla “sürüm” ortaya çıkabilir.

Kısa bir karşılaştırma:

• URL sürümlendirme: incelemesi en kolay, ama uzun süre paralel API'ler yaratabilir
• Header sürümlendirme: temiz URL'ler, ama hata ayıklaması zor
• Query sürümlendirme: başlamak hızlı, kötüye kullanımı kolay

Feature flag'ler farklı bir araçtır. Aynı sözleşme arkasında davranışı değiştirmeye izin verirler (örneğin yeni bir sıralama algoritması) ama istek/yanıt biçimi değiştiğinde sürümlendirme yerine geçmezler.

Bir yaklaşım seçin ve ona sadık kalın. Tutarlılık “mükemmel” seçimden daha önemlidir.

Geriye dönük uyumlu değişiklikler için başparmak kurallar

En güvenli zihniyet şudur: eski istemciler yeni özelliği asla öğrenmese bile çalışmaya devam etmelidir. Bu genellikle ekleme yapmak, var olanı değiştirmemek anlamına gelir.

Katkılayıcı değişiklikleri tercih edin: yeni alanlar, yeni uç noktalar, yeni isteğe bağlı parametreler. Bir şey eklediğinizde, sunucunun onu gerçekten isteğe bağlı tutması gerekir. Eski bir uygulama onu göndermiyorsa sunucu eskisi gibi davranmalıdır.

Bazı alışkanlıklar çoğu kırılmayı önler:

• Alan ekleyin, mevcut alanın türünü veya anlamını değiştirmeyin.
• Eksik girdiyi normal kabul edin ve mantıklı varsayılanlar kullanın.
• Bilinmeyen istek alanlarını görmezden gelin ki eski ve yeni istemciler birlikte var olabilsin.
• Hata formatlarını sabit tutun. Değiştirmeniz gerekiyorsa, hata payload'unu versiyonlayın.
• Davranış değişecekse, yeni bir uç nokta veya versiyon ekleyin; “sessiz” bir ince ayarın yerine.

Mevcut bir alanın anlamını versiyon yükseltmesi olmadan değiştirmekten kaçının. Örneğin, status=1 eskiden “ödendi” anlamındaysa ve siz bunu “yetkilendirildi” olarak yeniden kullanırsanız, eski uygulamalar yanlış kararlar verir ve kullanıcı şikâyetlerine kadar fark etmeyebilirsiniz.

Yeniden adlandırmalar ve kaldırmalar bir plan gerektirir. En güvenli desen, eski alanı tutup yeni alanı yan yana eklemektir. Yanıtlarda her ikisini de doldurun, isteklerde her ikisini de kabul edin ve kimlerin eski alanı kullandığını loglayın. Emeklilik penceresi sona ermeden eski alanı kaldırmayın.

Küçük ama etkili bir alışkanlık: yeni bir zorunlu iş kuralı getirirken, ilk günden istemciyi sorumlu kılmayın. Önce kuralı sunucuya koyun ve varsayılan davranışla çalıştırın; sonra kullanıcıların çoğu güncellendiğinde istemcinin yeni değeri göndermesini zorunlu kılın.

Basit bir sürüm ve emeklilik politikası belirleyin

Kurallar yazılı ve sıkıcı olduğunda sürümlendirme en iyi çalışır. Politikayı ürün, mobil ve backend ekiplerinin gerçekten uygulayacağı kadar kısa tutun.

Destek pencerileriyle başlayın. Yeni bir sürüm yayınlandıktan sonra eski API sürümlerini ne kadar süre çalıştıracağınızı (örneğin 6–12 ay) ve istisnaları (güvenlik, yasal değişiklikler) belirleyin.

Sonra istemcileri kırmadan önce nasıl uyaracağınızı tanımlayın. Bir emeklilik sinyali seçin ve her yerde kullanın. Yaygın seçenekler arasında Deprecation: true gibi bir yanıt başlığı veya seçili yanıtlarda "deprecation": {"will_stop_working_on": "2026-04-01"} gibi bir JSON alanı bulunur. Önemli olan tutarlılıktır: istemciler bunu algılayabilmeli, panolar raporlayabilmeli ve destek ekipleri açıklayabilmelidir.

Minimum desteklenen uygulama sürümünü belirleyin ve uygulama biçimini açıkça duyurun. Beklenmedik sert blokajlardan kaçının. Pratik bir yaklaşım:

1. Yumuşak bir uyarı dönün (örneğin uygulama içi güncelleme istemi tetikleyen bir alan).
2. İletilen son tarihten önce zorunlu hale getirmeyin.

Eğer isteği engellerseniz, insan için anlaşılır bir mesaj ve makine tarafından okunabilir bir kod içeren net bir hata payload'u döndürün.

Son olarak, kırıcı değişiklikleri kim onaylayabilir ve hangi dokümantasyon gerektiğine karar verin. Basit tutun:

• Bir sahibi kırıcı değişiklikleri onaylar.
• Kısa bir değişiklik notu neyin değiştiğini, kimlerin etkilendiğini ve geçiş yolunu açıklar.
• Test planı en az bir eski uygulama sürümünü içerir.
• Emeklilik tarihi, deprecate başlatıldığında belirlenir.

Eski uygulamaları çalışır tutan adım adım rollout planı

Mobil kullanıcılar ilk gün hepsi güncelleme yapmaz; en güvenli yaklaşım yeni bir API yayınlarken eskiyi dokunmadan bırakmak ve sonra trafiği kademeli taşımaktır.

Önce v2'nin neyi değiştirdiğini tanımlayın ve v1 davranışını kilitleyin. v1'i bir vaat gibi ele alın: aynı alanlar, aynı anlamlar, aynı hata kodları. v2 farklı bir yanıt şekli gerektiriyorsa v1'i v2'ye uydurmaya çalışmayın.

Sonra v2'yi paralel çalıştırın. Bu ayrı rotalar (ör. /v1/... ve /v2/...) veya aynı gateway altında ayrı handler'lar şeklinde olabilir. Paylaşılan mantığı tek bir yerde tutun, ama sözleşmeyi ayrı tutun ki v2 refaktörü yanlışlıkla v1'i değiştiremesin.

Ardından mobil uygulamayı v2'yi tercih edecek şekilde güncelleyin. Basit bir fallback ekleyin: v2 “desteklenmiyor” (veya bilinen başka bir hata) dönerse v1'e yeniden deneyin. Bu, kademeli yayınlarda ve gerçek dünya ağ koşullarında yardımcı olur.

Uygulamayı yayına aldıktan sonra benimsemeyi ve hataları izleyin. Yararlı kontroller şunlardır:

• v1 vs v2 istek hacmi uygulama sürümüne göre
• v2 için hata oranı ve gecikme
• yanıt ayrıştırma hataları
• ağla ilgili ekranlara bağlı çökme olayları

v2 stabil hale geldiğinde v1 için net emeklilik uyarıları ekleyin ve bir takvim duyurun. v1'i yalnızca kullanım kabul edilebilir bir eşikten düştüğünde kaldırın (örneğin birkaç hafta boyunca %1–2'nin altında).

Örnek: GET /orders isteğini filtreleme ve yeni statülerle destekleyecek şekilde değiştiriyorsunuz. v2 status_details eklerken v1 aynı kalır. Yeni uygulama v2'yi çağırır, ama bir uç durumda v1'e geri döner ve sipariş listesini hâlâ gösterir.

Sunucu tarafı uygulama ipuçları

Çoğu rollout kırılması, sürüm işleme kodunun controller'lara, yardımcılarına ve veritabanı koduna dağılması yüzünden olur. "Bu istek hangi sürüm?" kararını tek bir yerde tutun ve geri kalan mantığı öngörülebilir yapın.

Sürüm yönlendirmesini tek bir kapının arkasına koyun

Bir işaret seçin (URL segmenti, header veya uygulama build numarası) ve bunu erken normalize edin. Her isteğin aynı yolu izlemesi için tek bir modül veya middleware içinde uygun handler'a yönlendirin.

Pratik bir desen:

• Sürümü bir kez ayrıştırın (ve loglayın).
• Sürümü bir registry'de handler'a eşleyin (v1, v2, ...).
• Paylaşılan yardımcıları sürümden bağımsız tutun (tarih ayrıştırma, auth kontrolleri), yanıt biçimi mantığını burada tutmayın.

Sürümler arasında kod paylaşırken dikkatli olun. Paylaşılan bir kodda v2 hatasını düzeltmek, v1 davranışını kazara değiştirebilir. Çıktı alanlarını veya doğrulama kurallarını etkileyen mantığı versiyonlanmış tutun veya versiyon-spesifik testlerle kapsayın.

Rollout sırasında veri değişikliklerini uyumlu tutun

Veritabanı migrasyonları her iki sürüm için de çalışmalı. Önce kolon ekleyin, gerekiyorsa backfill yapın ve sadece daha sonra kısıtlamaları kaldırın veya sıkılaştırın. Rollout sırasında yeniden adlandırma veya anlam değiştirmekten kaçının. Format değiştirmek gerekiyorsa, kısa bir süre her iki formatı da yazmayı düşünün.

Hataları öngörülebilir yapın. Eski uygulamalar bilinmeyen hataları genellikle “bir şeyler ters gitti” şeklinde ele alır. Tutarlı HTTP statüleri, sabit hata kimlikleri ve istemcinin ne yapması gerektiğini (yeniden dene, yeniden kimlik doğrula, güncelleme göster) söyleyen kısa mesajlar kullanın.

Son olarak, eski uygulamaların göndermediği alanlara karşı korunma sağlayın. Güvenli varsayılanlar kullanın ve açık, sabit hata detaylarıyla doğrulama yapın.

Sürümlemeden etkilenen mobil uygulama hususları

Kullanıcılar eski bir build üzerinde haftalarca kalabildiğinden sürümlendirme aynı anda birden fazla istemci sürümünün sunucularınızı çağıracağını varsaymalıdır.

Büyük bir kazanım istemci tarafında toleranstır. Sunucu bir alan eklediğinde uygulama ayrıştırma veya çökme yapıyorsa bunu “rastgele” rollout hatası olarak hissedersiniz.

• Bilinmeyen JSON alanlarını görmezden gelin.
• Eksik alanları normal kabul edin ve varsayılanlar kullanın.
• Null'larla güvenli bir şekilde başa çıkın (alanlar migrasyon sırasında nullable olabilir).
• Sözleşme garanti etmiyorsa dizi sırasına güvenmeyin.
• Hata işleme kullanıcı dostu olsun (yeniden dene durumu boş ekrandan iyidir).

Ağ davranışı da önemlidir. Rollout sırasında yük dengeleyiciler veya cache'ler arkasında karışık sunucu sürümleri olabilir ve mobil ağlar küçük sorunları büyütebilir.

Net zaman aşımı ve yeniden deneme kuralları seçin: okuma çağruları için kısa zaman aşımı, yüklemeler için biraz daha uzun ve sınırlı backoff'lu yeniden denemeler. Oluşturma veya ödeme benzeri çağrılar için idempotentliği standart yapın ki yeniden deneme çift gönderime yol açmasın.

Kimlik doğrulama değişiklikleri eski uygulamaları hızlıca kilitleyebilir. Token formatını, gerekli scope'ları veya session kurallarını değiştiriyorsanız, her iki token tipinin de çalıştığı bir çakışma penceresi bırakın. Anahtarları veya claim'leri rotasyon yapmanız gerekirse, aynı gün içinde kesme yerine kademeli bir geçiş planlayın.

Her isteğe uygulama meta verisi gönderin (örneğin uygulama sürümü ve platform). Bu, hedefli uyarılar döndürmeyi kolaylaştırır utan fork atmadan.

Sürpriz olmadan izleme ve kademeli rollout

Kademeli bir rollout yalnızca farklı uygulama sürümlerinin ne yaptığını görebiliyorsanız işe yarar. Amaç basit: kimlerin hâlâ eski uç noktaları kullandığını bilmek ve sorunları herkese ulaşmadan önce yakalamak.

Günlük olarak API sürümüne göre kullanımı izleyerek başlayın. Toplam isteği saymak yeterli değildir. Aktif cihazları sayın ve giriş, profil ve ödemeler gibi kilit uç noktaları kırın. Bu, eski bir sürümün hâlâ “hayatta” olup olmadığını söyler.

Sonra hataları sürüm ve tür bazında izleyin. 4xx artışı genellikle sözleşme uyumsuzluğuna işaret eder (zorunlu alan değişmiş, enum kaymış, auth kuralları sıkılaşmış). 5xx artışı genellikle sunucu regresyonlarına işaret eder. Bunları sürüme göre görmek doğru çözümü hızlıca seçmenize yardım eder.

Mağaza içi staged rollout'ları patlama yüzeyini sınırlamak için kullanın. Açılımı adım adım artırın ve her adımda aynı panoları izleyin (ör. %5, %25, %50). En yeni sürüm sorun gösteriyorsa, rollout'u tam bir kesinti olmadan durdurun.

Geri alma tetiklerini önceden yazılı tutun, olay sırasında karar verilmesin. Yaygın tetikler:

• 15–30 dakika içinde belirli bir eşik üzerinde hata oranı
• giriş başarı oranında düşüş (veya token yenileme hatalarında artış)
• ödeme hatalarında artış (veya ödeme zaman aşımı artışı)
• belirli bir sürüme bağlı destek taleplerinde artış
• kritik bir uç noktada gecikme artışı

Sürüm ilişkili kesintiler için kısa bir olay playbook'u tutun: kimler çağrılır, riskli flag nasıl devre dışı bırakılır, hangi sunucu sürümüne geri dönülür ve eski istemciler hâlâ aktiffe emeklilik penceresinin nasıl uzatılacağı.

Örnek: gerçek bir yayında bir uç noktayı evrimleştirmek

Checkout klasik bir gerçek dünya değişikliğidir. Basit bir akışla başlarsınız, sonra güçlü bir ödeme adımı eklersiniz ve alanları iş diline göre yeniden adlandırırsınız.

Mobil uygulamanız POST /checkout çağırdığını varsayın.

v1'de ne kalır, v2'de ne değişir

v1'de mevcut istek ve davranışı koruyun ki eski uygulama sürümleri ödemeleri sürpriz olmadan tamamlayabilsin. v2'de yeni akışı ve daha temiz isimleri tanıtın.

• v1 korur: amount, currency, card_token ve status=paid|failed gibi tek bir yanıt.
• v2 ekler: payment_method_id (card_token'ın yerini alır) ve uygulamanın ekstra bir adımı (verify, retry, redirect) idare etmesi için next_action alanı.
• v2 yeniden adlandırır: amount → total_amount, currency → billing_currency.

Eski uygulamalar sunucu güvenli varsayılanlar uyguladığı için çalışmaya devam eder. Eğer v1 isteği next_action bilmiyorsa sunucu mümkünse ödemeyi tamamlar ve aynı v1 tarzı sonucu döner. Eğer yeni adım zorunluysa, v1'e kafa karıştırıcı bir genel hata yerine requires_update gibi net bir hata kodu dönün.

Benimseme, emeklilik ve rollback

Kullanımı sürüme göre izleyin: checkout çağrılarını hangi oranda v2 alıyor, hata oranları nasıl ve kaç kullanıcı sadece v1'i destekleyen build çalıştırıyor. v2 kullanımı tutarlı şekilde yüksekse (ör. birkaç hafta boyunca %95+), v1 için bir emeklilik tarihi seçin ve duyurun (sürüm notları, uygulama içi mesajlar).

Lansman sonrası bir sorun çıkarsa rollback sıkıcı olmalı:

• Trafiği daha fazla v1 davranışına yönlendirin.
• Yeni ödeme adımını sunucu tarafı bir flag ile devre dışı bırakın.
• Her iki alan setini de kabul etmeye devam edin ve otomatik dönüştürdüğünüz kayıtları loglayın.

Sessiz kırılmalara yol açan yaygın hatalar

Çoğu mobil API hatası yüksek sesle gelmez. İstek başarılı olur, uygulama çalışmaya devam eder ama kullanıcılar eksik veri, yanlış tutarlar veya işe yaramayan butonlar görür. Bu sorunlar tespit edilmesi zor çünkü genellikle kademeli rollout sırasında eski sürümleri hedef alır.

Yaygın nedenler:

• Alanları değiştirmek veya kaldırmak (veya türünü değiştirmek) net bir versiyon planı olmadan
• Yeni istek alanını hemen zorunlu yapmak, böylece eski uygulamalar reddedilmeye başlar
• Sadece yeni uygulamanın var olduğunu varsayan bir veritabanı migrasyonu yayınlamak
• v1'i yüklemelere göre değil aktif kullanıma göre emekli etmek
• Arka plan işleri ve webhook'ları unutmak; bunlar hala eski yükleri çağırıyor olabilir

Somut bir örnek: total alanı string ("12.50") iken siz bunu sayıya (12.5) çeviriyorsunuz. Yeni uygulamalar sorunsuz görünür. Eski uygulamalar bunu sıfır olarak alabilir, gizleyebilir veya belirli ekranlarda çöker. İstemci hatalarını uygulama sürümüne göre izlemezseniz bu gözden kaçabilir.

Hızlı kontrol listesi ve sonraki adımlar

Sürümlendirme, zekice uç nokta isimlendirmesinden çok her yayın öncesi aynı güvenlik kontrollerini tekrar etmektir.

Yayın öncesi hızlı kontroller

• Değişiklikleri ekleyici tutun. Eski uygulamaların okuduğu alanları kaldırıp yeniden adlandırmayın.
• Yeni alanlar eksik olduğunda eskisi gibi davranacak güvenli varsayılanlar sağlayın.
• Hata yanıtlarını sabit tutun (durum + biçim + anlam).
• Enum'lara dikkat edin ve mevcut bir değerin anlamını değiştirmeyin.
• Birkaç gerçek eski uygulama isteğini tekrar oynatın ve yanıtların hala ayrıştırıldığını doğrulayın.

Rollout sırasında ve emeklilik öncesi hızlı kontroller

• Uygulama sürümüne göre benimsemeyi izleyin. v1'den v2'ye net bir eğri görmek istersiniz, düz bir çizgi değil.
• Sürüme göre hata oranlarını izleyin. Bir sıçrama genellikle eski istemcilerin ayrıştırma veya doğrulamada kırıldığını gösterir.
• En çok hataya neden olan uç noktayı önce düzeltin, sonra rollout'u genişletin.
• Aktif kullanım gerçekten düşük olduğunda emekli edin ve tarihi duyurun.
• Fallback kodunu emeklilik penceresinden sonra en son kaldırın.

Sürümlendirme ve emeklilik politikanızı tek sayfaya yazın, sonra kontrol listesini her seferinde takımınızın takip ettiği bir release gate'e dönüştürün.

Eğer dahili araçlar veya müşteri-facing uygulamalar için no-code bir platform kullanıyorsanız, API'yi bir sözleşme olarak ele almak yine yardımcı olur. AppMaster (appmaster.io) kullanan ekipler için, gereksinimler değişirken backend ve istemci uygulamalarını yeniden üretebilme imkânı sayesinde v1 ve v2'yi yan yana tutmak genellikle daha kolaydır.