API doğrulama kurallarını mobil uygulamaları bozmadan değiştirin

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

Mobil uygulamalar anında güncellenmez. Sunucuda bugün bir kuralı sıkılaştırırsanız, yarın sabah hâlâ eski sürümde olan kullanıcıları kırabilirsiniz. Backend hızlı gönderilir, ama uygulama sürümleri mağaza onayları, kademeli dağıtımlar ve güncelleme yapmayan kullanıcıların hızıyla hareket eder.

Doğrulama genellikle katmanlar arasında bölünür ve bu katmanlar birbirinden sapar. Bir alan uygulama arayüzünde isteğe bağlı olabilir, API'de zorunlu olabilir ve veritabanında tekrar farklı uygulanabilir. Küçük uyumsuzluklar bile (boşlukları kırpma, emojileri reddetme, tarih formatlarını değiştirme) önceden çalışan bir isteği reddedilen hale getirebilir.

Doğrulama genellikle birkaç yerde yaşar:

• Mobil istemci (kullanıcının yazıp gönderebilecekleri)
• API (backend’in kabul ettikleri)
• Veritabanı (gerçekte saklanabilenler)
• Üçüncü taraf servisler (ödeme, mesajlaşma, kimlik sağlayıcıları)

İşler “bozulduğunda”, genelde sıkıcı ama can yakıcı olur: 400 hatalarında ani artış, sonsuz dönen bir ödeme butonu, kaydedemeyen profil ekranı veya belirsiz bir mesajla sıfırlanan bir form. Kullanıcılar bunu bir doğrulama değişikliğine bağlamaz; sadece uygulamanın çalışmayı kestiğini görürler.

Gizli maliyet çabuk birikir: destek talepleri, kötü yorumlar, iadeler ve kullanıcı kaybı. Hotfix gönderseniz bile uygulama mağazası onay süresi ve kullanıcıların yüklemesi için geçen süre vardır.

Daha güvenli doğrulama değişiklikleri için basit bir zihinsel model

API doğrulamasını değiştirirken iki soruyu ayırın:

1. Sunucu isteği anlayabiliyor mu?
2. Sunucu bunu kabul etmeli mi?

Çoğu kırılma bu iki sorunun karıştırılmasından doğar.

Format validation şu soruyu yanıtlar: “İstek iyi biçimlendirilmiş mi?” Zorunlu alanlar, tipler, maksimum uzunluk ve temel desenler buna girer. Sunucu yapıyı ayrıştıramıyorsa veya şekle güvenemiyorsa, hızlıca reddetmek adildir.

Business rules ise: “Geçerli bir şekil verildiğinde bu izinli mi?” Buna uygunluk kontrolleri, politika limitleri, ülke kısıtları ve diğer verilere bağlı kurallar girer. Bu kurallar daha sık değişir, bu yüzden kademeli bir dağıtım için alan bırakmak istersiniz.

Daha güvenli bir varsayılan, mevcut kuralları sıkılaştırmaktan çok ekleyici değişiklikleri tercih etmektir. Yeni isteğe bağlı bir alan eklemek, eski ve yeni formatları aynı anda kabul etmek veya izin verilen değerleri genişletmek genelde güvenlidir. Bir alanı sıkılaştırmak (zorunlu yapmak, maksimum uzunluğu küçültmek, karakterleri yasaklamak) takımların başını ağrıtır.

Hata sözleşmenizi sıkıcı ve sabit tutun. Her seferinde aynı yapıyı kullanın, tutarlı anahtarlarla (örneğin: code, field, message, details). Mesajlar gelişebilir, ama anahtarlar değişmemeli ki eski uygulamalar hataları çökmeden işleyebilsin.

Ne zaman hemen zorunlu kılacağınız hakkında pratik karar kuralları:

• Ayrıştırmayı veya güvenliği bozan durumlar: şimdi zorunlu kılın.
• Veri kalitesini artıran değişiklikler: önce uyarı verin, sonra zorunlu kılın.
• Yeni politika veya fiyatlandırma kuralı: bunu kademeli uygulayıp uygulama sürümleriyle hizalayın.
• Etkisi bilinmeyen değişiklikler: sert hatalar yerine öncelikle telemetriyle başlayın.
• Kullanıcıya görünen her şey: hatayı eyleme geçirilebilir ve spesifik yapın.

Bu, sunucuyu zorunlu olması gereken yerlerde sıkı tutar, mobil dağıtım hızının gerçek kısıt olduğu yerlerde ise esnek davranır.

Üretime dokunmadan önce değişimi planlayın

Doğrulamayı güncellemeden önce neyin değişeceğini ve eski uygulama sürümlerinin ne olacağını tam olarak yazın. Bu adım küçük bir sunucu geçişinin bir mobil hata dalgasına dönüşmesini önler.

Kuralları düz anlatımla ve gerçek payload örnekleriyle tanımlayın. “Telefon ülke kodu içermeli” demek, “E.164 gerekli” demekten daha açıktır. Şu anda geçen birkaç örnek isteği ve yapılan değişiklikten sonra geçmesi gereken yeni versiyonları ekleyin.

Sonra mobil gerçeğinizi haritalayın: hangi uygulama sürümleri hâlâ aktif ve gelecek birkaç hafta boyunca ne gönderecekler? iOS ve Android farklı hızlarda ilerliyorsa, onları ayrı değerlendirin. Burada hemen uygulayıp uygulayamayacağınıza veya kademeli doğrulama uygulamanız gerekip gerekmediğine karar verirsiniz.

Basit bir kontrol listesi yardımcı olur:

• Eski ve yeni kuralları 2-3 somut istek örneğiyle belgeleyin.
• Trafiğin hangi yüzdesinin eski payload göndermeye devam edeceğini (sürüm bazında) tahmin edin.
• Dağıtım yolunu seçin: önce uyarı, sonra uç nokta veya alan bazında kademeli zorunluluk, ardından tam uygulama.
• Başarı metriklerini ve geri alma koşullarını tanımlayın (hata oranı, destek talepleri, dönüşüm).
• İç takımları hizalayın: destek için metinler, QA senaryoları, sürüm notları.

Ayrıca sürümler çakışırken yanıtların nasıl güvenli kalacağını kararlaştırın. Eğer reddetmeniz gerekiyorsa, hataları öngörülebilir ve makine tarafından okunabilir yapın. Eski payloadları kabul edebiliyorsanız, geriye dönük uyumlu davranışı şimdi planlayın, olay sırasında değil.

Önce uyarılarla başlayın, sert hatalarla değil

API doğrulama kurallarını mobil uygulamaları bozmadan değiştirmek istediğinizde, genellikle en güvenli ilk hamle şudur: isteği kabul edin ve ileride geçersiz olacak şey hakkında uyarı verin. Bu, bugün kullanıcıların çalışmaya devam etmesini sağlar ve “kötü” girdinin hâlâ ne sıklıkta göründüğünü öğrenmenize yardımcı olur.

İyi bir uyarı, hangi alanın sorunlu olduğunu, gelecekte neden reddedileceğini ve yeni kuralın ne olduğunu müşteriye söyler. İsteği engellememelidir. Bunu yarının doğrulamasının bir ön gösterimi gibi düşünün.

Uyarıların nerede duracağı, kimin görmesi gerektiğine bağlıdır. Birçok ekip karışık bir yaklaşım kullanır:

• QA yapıları için yanıt gövdesinde küçük bir warnings dizisi.
• Ağ geçitleri ve hata ayıklama araçları için yanıt başlıkları.
• App sürümleri arasında etkiyi ölçmek için sunucu logları ve telemetri.

Uyarıları kullanıcı açısından güvenli tutun. Gizli verileri, tokenları, tam e-postaları, telefon numaralarını veya hassas ham girdileri yansıtmayın. Gerekirse maskelayın (örneğin son 2 rakamı göster) ve sabit tanımlayıcılar (örneğin request ID) tercih edin.

“Yakında kırılacak” vakaları triyaj etmek için makine tarafından okunabilir bir kod ve bir son tarih ekleyin. Örneğin: kod VALIDATION_WILL_FAIL_SOON, field phone, rule E164_REQUIRED, enforce_after 2026-03-01. Bu, logları filtrelemeyi, ticket açmayı ve uyarıları belirli uygulama sürümleriyle eşlemeyi kolaylaştırır.

Pratik bir örnek: gönderim için country alanını zorunlu hale getirmeyi planlıyorsanız, önce country eksik olsa bile isteği kabul edin, uyarı dönün ve kaç isteğin hala eksik gönderildiğini kaydedin. Bu sayı azaldığında ve uygulama güncellemesi yayıldığında, zorunlu hale geçin.

Mobil sürümlerin yetişebileceği şekilde kademeli zorunluluk

Mobil uygulamalar sizin tam kontrolünüzde olmayan bir takvimle dağıtılır. Bazı kullanıcılar hızlıca günceller, bazıları haftalarca eski sürümü kullanır. Bir doğrulama kuralını bir gecede reddettiğinizde, rastgele hatalar gibi görünen ani kesintiler yaratırsınız.

Önce “yumuşak hata” ile başlayın: isteği kabul edin ama yeni kurallara göre başarısız olacağını kaydedin. Alanı, nedeni, uygulama sürümünü ve uç noktayı loglayın. Bu, kimseyi kırmadan önce gerçek rakamlar verir.

Sonra küçük, geri alınabilir adımlarla sıkılaştırın:

• Trafiğin küçük bir yüzdesine daha sıkı kontroller uygulayın (örneğin %1, sonra %10, sonra %50).
• Zorunluluğu uygulama sürümüne göre gate’leyin, böylece eski sürümler yumuşak hata modunda kalırken yeni sürümler sert hata alır.
• Cohort bazlı dağıtım yapın (önce dahili ekip, sonra beta kullanıcılar, sonra herkes).
• Zorunluluğu feature flag’in arkasında tutun ki hızlıca kapatabilesiniz.
• Bir zaman çizelgesi belirleyin: şimdi uyarın, sonra zorunlu yapın, benimsenme sonrası geçici davranışı kaldırın.

Örnek: telefon numaralarında ülke kodu zorunlu kılmak istiyorsunuz. 1. hafta, ülke kodu olmasa bile kabul edin ama “ülke kodu eksik” olarak etiketleyin. 2. hafta, sadece düzeltilmiş sürümlerde zorunlu hale getirin. 3. hafta, yeni hesaplar için zorunlu yapın. 4. hafta, herkes için zorunlu kılın.

Kırılmayı azaltan geriye dönük uyumlu sunucu yanıtları

Doğrulama kurallarını değiştirirken, genelde güvenli hamle sunucu davranışını önce değiştirmektir, uygulamayı değil. Mobil kullanıcılar eski sürümlerde haftalarca kalabildiği için sunucu bir süre hem “dünkü uygulama” hem de “bugünkü kurallar” ile çalışabilmelidir.

Pratik yaklaşım, geçiş penceresi boyunca hem eski hem yeni payload biçimlerini kabul etmektir. phoneı phone_number olarak yeniden adlandırırsanız, her iki alanı da kabul edin. Eğer her ikisi de varsa, birini seçip loglayın. Hiçbiri yoksa önce uyarı verin, sonra zorunluluk aşamasına geçin.

API’yi desteklemesi kolay küçük, öngörülebilir desenler kullanın:

• Belirli bir süre boyunca eski ve yeni alan adlarını/yapılarını kabul edin.
• Yeni zorunlu alanları geçici olarak isteğe bağlı kabul edin ve uygun yerlerde sunucu tarafında güvenli varsayılanlar uygulayın.
• Yanlışlıkla yapı değişse bile yanıt formatlarını sabit tutun.
• Uygulamalar güvenle dallanabilsin diye tutarlı hata kodları döndürün.
• “Geçici” mantığın kalıcı hale gelmemesi için dahili bir kullanım süresi ve bitiş tarihi belirleyin.

Varsayılanlar ekstra dikkat ister. Bir varsayılan geçerli olmalı, sadece kullanışlı olmamalıdır. Eksik country alanını US yapmak hesabı sessizce bozabilir. Çoğu durumda daha güvenli hareket: isteği kabul et, uyarı kaydet ve daha sonra düzeltme iste.

Hata yanıtlarını tutarlı tutun. Uygulama { code, message, fields } bekliyorsa, bu yapıyı koruyun. Yeni alanlar ekleyebilirsiniz, ancak dağıtım sırasında eski alanları kaldırmaktan veya yeniden adlandırmaktan kaçının. Eski uygulamalar, yanıtı ayrıştıramayıp hata verdiğinde kullanıcılar için kötü bir deneyim oluşur.

Uygulamaların güvenle tüketebileceği doğrulama hataları tasarlayın

En büyük risk genellikle kuralın kendisi değil, uygulamanın hatayı nasıl okuduğudur. Pek çok uygulama belirli bir yapı, anahtar veya mesaj bekler. Küçük bir değişiklik bile yardımcı bir uyarıyı genel bir “bir şeyler yanlış” bantına dönüştürebilir.

Alan düzeyinde hatalar için iki soruyu yanıtlayan bir yapı hedefleyin: ne başarısız oldu ve neden? Kısa kullanıcıya yönelik bir mesaj tutun, ama uygulamanın güvenle tepki verebilmesi için makine tarafından okunabilir ayrıntılar ekleyin (bir alanı vurgulama, bir butonu engelleme veya spesifik bir ipucu gösterme).

Dayanıklı bir desen şöyle görünür:

• code: VALIDATION_FAILED gibi sabit bir string
• errors[]: field, rule, code, message içeren öğeler listesi
• request_id (isteğe bağlı): destek izleri için yardımcı olur

Sadece “Geçersiz giriş” döndürmek yerine: email format nedeniyle başarısız oldu, parola min_length kuralını geçemedi gibi detaylar verin. UI daha sonra değişse bile uygulama code ve field ile güvenli şekilde eşleyebilir.

Uygulamanın muhtemelen dayandığı anahtarları yeniden adlandırmayın (örneğin errorsı violations yapmak). Şemayı geliştirmek zorundaysanız, eski mobil sürümler neredeyse giderilmiş olana kadar yeni alanlar ekleyin ama eski olanları kaldırmayın.

Yerelleştirme de ters tepebilir. Bazı uygulamalar ham sunucu metinlerini gösterir. Güvende kalmak için hem sabit bir code hem de varsayılan, düz bir message gönderin. Uygulama codeu kendi diline çevirebilir; çeviremiyorsa varsayılan mesajı gösterir.

Dağıtım sırasında izleme ve telemetri

Dağıtımı ölçülmüş bir deney gibi ele alın. Amaç basit: kullanıcılar hissedeceği bir sorun oluşmadan önce sıkıntıyı fark etmek.

Günde üç sayıyı takip edin: verdiğiniz uyarı sayısı, reddedilen isteklerin sayısı ve hangi uç noktaların etkilendiği. Uyarılar önce yükselmelidir (çünkü onları açtınız), sonra istemciler güncellendikçe düşmelidir. Reddedilmeler, siz bilinçli olarak sıkılaştırana kadar düşük kalmalıdır.

Pano segmentasyonu önemlidir; mobil sorunlar nadiren uniform olur. Uygulama sürümüne, işletim sistemine (iOS vs Android), cihaz tipine ve bölgeye göre kırın. Tek bir eski uygulama sürümü riskin çoğunu taşıyabilir, özellikle bazı pazarlarda güncellemeler yavaşsa.

Uyarılar kullanıcı etkisine odaklı olmalı, sadece sunucu sağlığına değil:

• Doğrulama ile ilgili 400’lerdeki ani artışlar
• Kayıt, giriş, ödeme veya “profili kaydet” gibi ana akışlarda düşüşler
• Yeniden deneme, zaman aşımı veya istemci tarafı “bilinmeyen hata” bildirimlerinde sıçramalar
• Uyarıların arttığı ama düzeltici uygulama sürümünün benimsenmediği uç noktalar

Ayrıca sessiz hatalara dikkat edin: kısmi kayıtlar, tekrar eden arka plan yeniden denemeleri veya UI iyi görünmesine rağmen sunucunun veriyi kabul etmediği döngüler. API olaylarını ürün olaylarıyla korele edin (örneğin, uygulama “ProfileSaved” gönderdi ama sunucu yazmayı reddetti).

Geri alma oyun planını önceden yazın. Önce neyi geri alacağınızı karar verin: enforcement toggle, yeni kural veya yanıt yapısı. Kararı net eşiklere bağlayın (örneğin belirli bir uygulama sürümünde doğrulama 400’leri belirli bir oranı aşarsa).

Örnek: kayıt doğrulamasını sıkılaştırırken ödemeyi bozmamak

Daha temiz veri için kayıt sırasında telefon ve adres kurallarını sıkılaştırmak isteyebilirsiniz, ama aynı alanlar ödeme sırasında da kullanılıyorsa. Anahtarı fazlaca hızlı çevirirseniz, eski mobil uygulamalar en kötü anda — birinin ödeme yapmaya çalıştığı anda — başarısız olmaya başlar.

Bunu net aşamalarla, yaklaşık bir ay sürecek bir dağıtım olarak ele alın. Amaç, veriyi iyileştirmek ama doğrulamayı beklenmedik bir kesintiye çevirmemektir.

Gerçekçi bir hafta hafta plan:

• 1. Hafta: Mevcut formatları kabul etmeye devam edin, fakat sunucu tarafında uyarılar ekleyin. Yeni kurallara göre başarısız olacak her isteği (ülke kodu olmayan telefonlar, posta kodu eksik adresler vb.) loglayın ve uygulama sürümüne göre sayın.
• 2. Hafta: Hoşgörülü kalın ama yanıtlarda normalize edilmiş veriler döndürmeye başlayın. Örneğin, orijinal phone yanında phone_e164 döndürün ve uygulama tek bir string göndermiş olsa bile yapılandırılmış bir address objesi döndürün.
• 3. Hafta: Daha sıkı kuralları sadece yeni uygulama sürümleri için zorunlu kılın. Bunu sürüm başlığı veya build’e bağlı feature flag ile gate’leyin ki eski sürümlerdeki checkout çalışmaya devam etsin.
• 4. Hafta: Kabul oranı eşiğine (örneğin checkout trafiğinin %90-95’i yeni doğrulamayı geçen sürümlerdeyse) ve uyarı oranı kabul edilebilir düzeye düştüğünde tam zorunluluğa geçin.

Önemli olan checkout’ın çalışmaya devam etmesi ve ekosistem yaklaştıkça doğrulamanın kademeli olarak sıkılaştırılmasıdır.

Kaçınılması gereken yaygın hatalar ve tuzaklar

Doğrulama değişiklikleri tahmin edilebilir nedenlerle başarısız olur: daha katı bir kural bir yerde yayınlanır ve aylardır kullanılan bir uygulama hâlâ eski şekli göndermeye devam eder.

Yaygın tuzaklar:

• Önce veritabanı kısıtı eklemek; API buna hazır değilse yönetilemez bir sunucu hatası olur ve yardımcı hata mesajı verme şansını kaybedersiniz.
• İstek doğrulamasını sıkılaştırıp aynı sürümde yanıt şemasını değiştirmek; her iki uç da hareket edince yeni uygulamalar bile kırılabilir.
• Dağıtım planı olarak uygulama mağazası güncellemelerine güvenmek; birçok kullanıcı güncellemeyi erteleyebilir veya bazı cihazlar güncelleyemez.
• “Invalid input” gibi belirsiz hatalar dönmek; kullanıcı düzeltemez, destek teşhis edemez, mühendisler başarısız olanı ölçemez.
• Eski payloadlar için otomatik testleri atlamak. Gerçek eski istekleri yeniden oynatmazsanız tahmin yürütmüş olursunuz.

Basit bir kural: aynı anda yalnızca bir boyutu değiştirin. Bir süre eski isteği kabul edin, sonra yeni alanı zorunlu kılın. Yanıtı da değiştirmeniz gerekiyorsa, çoğu istemci hazır olana kadar eski alanları (deprecate edilmiş bile olsa) bırakın.

Hataları eyleme geçirilebilir hale getirin. “Alan adı + sebep + ipucu” destek yükünü azaltır ve kademeli zorlama daha güvenli hale getirir.

Daha sıkı kuralları uygulamadan önce hızlı kontrol listesi

Çoğu olay, kaçırılan küçük bir varsayımdan kaynaklanır, kuralların “çok katı” olmasından değil. Zorunluluğa geçmeden önce şu soruları açıkça yanıtlayın:

• Sunucu belirli bir pencere için eski payload şeklini kabul edebilir mi (en azından loglayıp uyarı verirken) ki eski uygulama sürümleri çalışmaya devam etsin?
• Yeni kural başarısız olsa bile yanıtlar aynı JSON yapısını, alan adlarını ve hata anahtarlarını koruyacak mı?
• Gerçek bir uyarı aşamanız (eski format görüldüğünde log veya sayaç) var mı, böylece benimseme tahminden öte ölçülebilir?
• Zorunluluğu hızlıca açıp kapatabiliyor musunuz (feature flag, konfigürasyon anahtarı veya istemci başına politika) redeploy gerektirmeden?
• Gerçek telemetriye dayanarak en eski aktif uygulama sürümünü ve kaç kullanıcının o sürümde olduğunu biliyor musunuz?

Eğer herhangi bir yanıta “emin değilim” ise, önce eksik parçayı ekleyin. Yaygın bir desen iyi çalışır: 1–2 sürüm döngüsü boyunca kabul et ve uyarı ver, sonra sadece yeni sürümler için zorunlu kıl, ardından herkes için zorunlu yap.

Sonraki adımlar: değişimi güvenle gönderin ve ilerlemeye devam edin

Doğrulama değişikliklerini hızlı bir backend düzeltmesi değil, bir ürün sürümü gibi ele alın.

Her şeyin bir sayfalık bir deprecation planını değişiklikleri merge etmeden önce yazın. Net olsun: ne değişiyor, kim sahip, uyarılar ne zaman başlıyor, zorunluluk ne zaman başlıyor ve “tamamlandı” ne demek.

Dağıtımı kontrol etmeyi kolaylaştırın:

• Sahipler ve tarihler atayın (uyarı başlangıcı, kısmi zorunluluk, tam zorunluluk, eski yolların kaldırılması).
• Sunucuda sürüm-düşünür doğrulama (veya feature flag) ekleyin ki eski uygulama sürümleri geriye dönük uyumlu davranış almaya devam etsin.
• Otomatik testleri her iki yolu da kapsayacak şekilde genişletin: legacy kabulü ve yeni kurallar.
• Uyarı sayısını ve sert hataları uygulama sürümüne, uç noktaya ve kurala göre ayıran panolar oluşturun.
• Geri alma talimatını önceden takvimleyin, kullanmanız gerekmeden önce bir kez prova edin.

Uyarılar yayına girdikten sonra ölçümü sürdürün. Uyarılar uygulama sürümüne göre azalmıyorsa, zorunluluk destek talepleri ve kötü yorumlar yaratır, veri temizliği sağlamaz.

Eğer kuralları ve iş mantığını merkezi bir yerde toplamak isterseniz, AppMaster (appmaster.io) gibi no-code bir platform yardımcı olabilir. Data Designer’da veriyi modelleyebilir, Business Process Editor’da mantığı ayarlayabilir ve backend’i yeniden üreterek mobil sürümler dağıtılırken doğrulama davranışının uyumlu kalmasını sağlayabilirsiniz.

Kesme tarihini iç paydaşlarla (destek, ürün, mobil, backend) yazılı olarak paylaşın. “Herkes biliyordu” bir plan değildir; yazılı bir tarih ve net bir sahip genelde işe yarar.