Mobil API'ler için JSON vs Protobuf: boyut, uyumluluk, hata ayıklama

Mobil uygulamalar için API formatının neden önemi var

Mobil bir uygulama, arka uç hızlı olsa bile yavaş hissedebilir. Genelde bunun nedeni sunucu zamanı değildir. Asıl neden çevresel faktörlerdir: hücresel gecikme, zayıf sinyal, yeniden denemeler ve telefonun ağ radyosunu uyandırma süresi. Bir ekran üç API çağrısı tetikliyorsa, o round-trip maliyetini üç kez ödersiniz.

Format ayrıca baytlar geldikten sonra olanları etkiler. Uygulama yine de yanıtı ayrıştırmalı, doğrulamalı ve UI modellerine eşlemelidir. Bu işler CPU kullanır, yani pil tüketimi. Eski telefonlarda ya da uygulama arka planda çalışırken küçük verimsizlikler hızla birikir.

Payload boyutu, bir istek ve yanıt için wire üzerinden gönderdiğiniz bayt sayısıdır; alan adları ve yapısal karakterler dahil. Daha küçük payload'lar genelde zayıf ağlarda daha hızlı indirme ve sınırlı planlarda daha az veri kullanımı anlamına gelir. Ayrıca radyo daha kısa süre aktif kaldığı ve CPU daha az ayrıştırma yaptığı için pil tüketimini azaltabilir.

Format seçimi, API'nizi güvenle nasıl evriltileceğini de değiştirir. Mobil sürümler web'e göre daha yavaştır: kullanıcılar geç günceller, bazıları asla güncellemez, ve uygulama mağazası incelemesi düzeltmeleri geciktirebilir. Eski istemcileri bozacak bir API değişikliği gönderirseniz, baskı altında birden fazla sürümü desteklemek zorunda kalabilirsiniz.

Hata ayıklama da önemlidir. JSON ile genelde günlüklerde payload'ı okuyup sorunu hızlıca görürsünüz. Protobuf gibi ikili formatlarda ise genelde ne olduğunu çözmek için şema ve doğru araçlar gerekir.

Uygulamada pratikte bu karar kötü ağlarda ekran başına yükleme süresini, veri ve pil kullanımını, eski uygulamaları bozmadan alan ekleme güvenliğini ve hataları ne kadar hızlı inceleyebildiğinizi etkiler.

JSON ve Protobuf basitçe

JSON ve Protobuf, aynı bilgiyi paketlemenin iki yoludur; böylece uygulama ve sunucu bir mesajın ne anlama geldiği konusunda anlaşır. Bunu yazılı bir not (JSON) ya da kompakt bir barkod (Protobuf) göndermek gibi düşünebilirsiniz.

JSON ile veriler her seferinde alan adlarıyla birlikte metin olarak gönderilir. Basit bir kullanıcı nesnesi şöyle görünebilir: {"id": 7, "name": "Sam"}. Bu haliyle okunabilir, bu da günlüklerde incelemeyi, hata raporuna yapıştırmayı veya temel araçlarla test etmeyi kolaylaştırır.

Protobuf ile veriler ikili baytlar olarak gönderilir. Alan adlarını "id" ve "name" gibi her defasında tekrar etmek yerine, iki taraf önceden 1'in id, 2'nin name olduğunu kabul eder. Mesaj daha küçük olur çünkü çoğunlukla değerler artı kısa sayısal etiketlerden oluşur.

Metin vs ikili, teoriyi bir kenara koyarsak

Pratik takas basittir:

• JSON kendini tanımlar: mesaj alan adlarını taşır.
• Protobuf şema odaklıdır: anlam paylaşılan bir tanım dosyasından gelir.
• JSON okunması ve elle düzenlenmesi kolaydır.
• Protobuf kompakt ve tutarlıdır, ancak araçlar olmadan okunamaz.

Bu paylaşılan tanım şemadır. Protobuf ile ekipler genellikle şemayı bir sözleşme olarak ele alır, sürümlendirir ve arka uç ile mobil istemciler arasında senkron tutarlar. JSON ile şema isteğe bağlıdır; birçok ekip yine bir şema belgelemeye devam eder (örneğin OpenAPI ile), ancak teknik olarak API şema olmadan da gönderilebilir.

Günlük işte bu işbirliğini değiştirir. Protobuf sizi daha resmi API değişikliklerine yönlendirir (alan ekle, eski alan numaralarını ayır, yeniden adlandırmalardan kaçın). JSON genelde daha gevşek değişikliklere izin verir, ama bu esneklik istemcilerin alanların her zaman mevcut olduğunu veya hep aynı tipte olduğunu varsaymasına bağlı sürprizler yaratabilir.

Gerçekte, JSON halka açık REST API'lerde ve hızlı entegrasyonlarda yaygındır. Protobuf ise gRPC servislerinde, dahili servisler arası trafiğinde ve bant genişliği ile gecikmenin kritik olduğu performans odaklı mobil uygulamalarda sıkça kullanılır.

Payload boyutu: wire üzerinde gerçekte ne değişir

Ham boyut önemlidir, ama detaylar daha çok önem taşır: hangi baytlar tekrar ediyor, hangi baytlar iyi sıkışıyor ve ne sıklıkla gönderiliyorlar.

JSON neden genelde daha büyük

JSON okunabilir metin taşır. En büyük maliyet genelde değerlerinizin etrafındaki kelimelerdir:

• Alan adları her nesnede tekrar eder ("firstName", "createdAt", "status").
• Sayılar metin olarak gönderilir, bu yüzden "123456" kompakt bir ikili tam sayıdan daha fazla bayt kullanır.
• Derin iç içe geçmişlik süslü parantezler, virgüller ve tırnaklar ekler.
• Güzel biçimlendirilmiş cevaplar istemciye yardımcı olmayan boşluk ekler.

API'niz 200 öğelik bir liste döndürüyorsa ve her öğe 10 alan adını tekrar ediyorsa, bu tekrar eden adlar payload'u domine edebilir.

Protobuf neden genelde daha küçük

Protobuf alan adlarını sayısal etiketlerle değiştirir ve kompakt bir ikili kodlama kullanır. Paketlenmiş (packed) kodlama tekrarlayan sayıları verimli saklayabilir (örneğin birçok ID). Ayrıca wire formatı typed olduğu için tam sayılar ve boolean'lar genelde JSON metin sürümlerinden daha az bayt alır.

Faydalı bir zihinsel model: JSON alan başına bir vergi öder (anahtar adı). Protobuf daha küçük bir alan başına vergi (etiket) öder.

Sıkıştırma karşılaştırmayı değiştirir

Gzip veya brotli ile JSON genelde çok küçülür çünkü tekrar eden stringler vardır ve alan adları çok iyi sıkışır. Protobuf da sıkışır, ama daha az belirgin tekrar olabilir, bu yüzden göreli kazanç daha küçük olabilir.

Uygulamada Protobuf genelde boyut olarak kazanır, ama sıkıştırma açıkken fark çoğu zaman daralır.

“Küçük” en çok ne zaman önemli

Payload boyutu, istekler sık veya ağlar kötü olduğunda en çok önem kazanır. Mobil bir uygulama roaming halindeyken her 10 saniyede bir güncelleme alıyorsa, her yanıt sadece biraz daha büyük olsa bile veri kullanımını hızlıca tüketebilir. Ayrıca chatty ekranlar (arama önerileri, canlı panolar) için ve düşük bant genişliğe sahip kullanıcılar için önemlidir.

Bir uç noktayı oturum başına yalnızca birkaç kez çağırıyorsanız, tasarruflar gerçek ama nadiren dramatiktir. Yüzlerce kez çağırılıyorsa, küçük farklar hızla göze batmaya başlar.

Hız ve pil: ayrıştırma, CPU ve gerçek kısıtlar

Mobilde ağ sadece hikayenin yarısıdır. Her yanıt çözümlenmeli, nesnelere dönüştürülmeli ve genelde yerel bir veritabanına yazılmalıdır. Bu işler CPU zamanı gerektirir ve CPU zamanı pil tüketir.

JSON metindir. Şunu yapmak gerekir: stringleri taramak, boşlukları işlemek, sayıları dönüştürmek ve alan adlarını eşleştirmek. Protobuf ikilidir. Bunların çoğunu atlar ve uygulamanın ihtiyaç duyduğu değerlere daha yakın çıkar. Birçok uygulamada bu, özellikle iç içe geçmiş payload'lar veya tekrar eden alan adlarıyla dolu listelerde, yanıt başına daha az CPU anlamına gelir.

Telefonda “daha hızlı” ne demektir

Ayrıştırma maliyetini en çok soğuk başlatma ve düşük seviye cihazlarda hissedersiniz. Uygulama açılır açılmaz büyük bir ana akış yüklüyorsa, daha yavaş çözümleme daha uzun boş ekran veya gecikmiş ilk etkileşim olarak görünebilir.

Protobuf'un otomatik olarak performansı düzeltmesini beklemeyin. Yanıtlar küçükse veya darboğaz resimler, TLS el sıkışması, veri tabanı yazmaları veya UI render ise, format seçimi fark yaratmayabilir.

Sunucu tarafı verimi de önemli

Kodlama ve çözümlenme sunucuda da gerçekleşir. Protobuf istekteki CPU'yu azaltıp verimi artırabilir, bu da birçok istemci sık sık poll veya sync yaptığında yardımcı olur. Ancak arka uç zamanınız çoğunlukla veri tabanı sorguları, cache veya iş mantığı tarafından domine ediliyorsa fark küçük olabilir.

Adil ölçüm yapmak için testleri kontrol altında tutun: aynı veri modelini ve kayıt sayılarını kullanın, sıkıştırma ayarlarını eşleştirin (veya her ikisi için sıkıştırmayı devre dışı bırakın), gerçekçi mobil ağlarda test edin (sadece hızlı Wi‑Fi değil) ve uçtan uca süre ile çözümleme CPU'sunu ölçün (sadece indirme süresi değil). En az bir düşük seviye cihazı dahil edin.

Basit bir kural: ikili formatlar, çok yapılandırılmış veriyi sık gönderdiğinizde ve çözümleme süresinin gecikme veya pil kullanımında anlamlı bir payı olduğunun gösterebildiğiniz durumlarda kendini amorti eder.

Geriye dönük uyumluluk: API'nizi güvenle nasıl evriltirsiniz

Geriye dönük uyumlu olmak, yeni bir sunucu sürümü gönderildikten sonra eski uygulama sürümünün çalışmaya devam etmesi demektir. Mobilde bu web'e göre daha fazla önem taşır çünkü kullanıcılar hemen güncellemez. Aynı anda üç veya dört uygulama sürümü sahada olabilir.

Pratik bir kural sunucu değişikliklerini ekleyici yapmak: sunucu eski istekleri kabul etmeli ve eski istemcilerin anlayabileceği yanıtlar göndermelidir.

JSON ile ekleyici değişiklik genelde yeni isteğe bağlı alanlar eklemek anlamına gelir. Eski istemciler kullanmadıkları alanları görmezden gelir, bu yüzden genelde güvenlidir. Yaygın tuzaklar JSON'un kendisinden çok bozan varsayımlardır: bir alanın tipini değiştirmek (string'ten sayı), bir alanı yeniden adlandırmak, ismi değişmeden anlamını değiştirmek veya stabil bir değeri daha açık uçlu hale getirmek.

Protobuf ile uyumluluk daha katıdır ama kurallara uyarsanız daha güvenilirdir. Alan numaraları sözleşmedir; alan adları değil. Bir alanı kaldırırsanız, numarasını yeniden kullanmayın. Numara ayırın. Ayrıca alan tiplerini değiştirmekten veya tekrarlanan ile tekrarlanmayan (repeated vs non-repeated) arasında geçiş yapmaktan kaçının; bunlar eski istemcileri kırabilir.

Her iki format için de güvenli değişiklik örnekleri şunlardır:

• Anlamlı varsayılanları olan yeni isteğe bağlı alanlar ekleyin.
• Enum değerleri ekleyin ve istemcilerin bilinmeyen değerlere toleranslı olmasını sağlayın.
• Mevcut alanların tipini ve anlamını sabit tutun.
• Alanları önce kullanım dışı bırakın, eski istemciler gitene kadar sonra kaldırın.

Sürümleme iki yaygın tarzda yapılır. Ekleyici evrim bir uç noktayı tutar ve şemayı zamanla büyütür; mobil için genelde uygundur. Sürümlü uç noktalar (v1, v2) kırıcı değişiklik gerektiğinde yardımcı olur ama test ve destek işini ikiye katlar.

Örnek: uygulamanız bir sipariş listesini gösteriyor. Teslim ETA eklemek istiyorsanız delivery_eta'yı isteğe bağlı ekleyin. status'ı zaman damgalarını içerecek şekilde yeniden kullanmayın. Yeni bir model gerekiyorsa, v2 yanıtını değerlendirin ama eski app nüfusu düşene kadar v1'i sunmaya devam edin.

Hata ayıklama ve gözlemlenebilirlik: neyin yanlış olduğunu görme

Mobil bağlantıda bir şey bozulduğunda genelde üç ipucunuz olur: istemci hatası, sunucu günlük satırı ve isteğin izi (trace). Format, bu ipuçlarının ne kadar hızlı yanıta dönüşeceğini etkiler.

JSON insan tarafından okunabilir olduğundan incelemesi kolaydır. Bir JSON gövdesini günlüğünden, proxy yakalamasından veya destek bileti içinden kopyalayıp hemen anlayabilirsiniz. Bu, bir sürüm sırasında hata ayıklarken ya da teknik olmayan bir ekip üyesinin uygulamanın gerçekten ne gönderdiğini doğrulaması gerektiğinde önemlidir.

Protobuf aynı derecede ayıklanabilir olabilir, ama bunu planlamalısınız. Yük ikili olduğu için alanları görmek için şema ve bir çözücü adımı gerekir. Birçok ekip bunu, ham baytlar yerine, istek meta verileriyle birlikte anahtar alanların güvenli çözümlenmiş bir özetini günlükleyerek ele alır.

Protobuf'u pratikte hata ayıklanabilir kılmak

Birkaç alışkanlık çok yardımcı olur:

• Tam mesaj yerine çözümlenmiş özetleri (ör. user_id, request_type, item_count) loglayın.
• .proto dosyalarını sürümlendirin ve olay müdahalesi yapanların erişebileceği yerde tutun.
• Her yanıtta ve günlük satırında istek kimliği ve trace ID bulundurun.
• Açık enum adları kullanın ve alanları birden fazla anlam için yeniden kullanmaktan kaçının.
• İş kurallarını erken doğrulayın ve okunabilir hata kodları döndürün.

Gözlemlenebilirlik ayrıca özel verileri sızdırmadan izleme yapmakla ilgilidir. Hangi verinin loglanabileceğine, hangisinin kırpılması gerektiğine ve hangisinin asla cihazdan çıkmaması gerektiğine erken karar verin. E‑posta, telefon numarası, kesin konum ve ödeme bilgilerinin günlüklerde depolanmadan önce filtrelenmesi gerekir.

Basit bir senaryo: destek ekibi bir kullanıcının zayıf mobil veriyle bir form gönderemediğini rapor eder. JSON ile yakalanan istekte eksik "country" alanını hemen görebilirsiniz. Protobuf ile aynı sonuca, günlüklerde "country: unset" gibi çözümlenmiş bir anlık görüntü ve şema sürümü kaydı varsa ulaşabilirsiniz.

Nasıl seçilir: adım adım karar süreci

JSON ve Protobuf arasında seçim yapmak nadiren tek seferlik, tüm şirketi etkileyen bir karar olur. Çoğu ekip gerçek kullanım temelinde uç nokta bazında karar verince daha başarılı olur.

Basit 5 adımlık süreç

Uç noktaları gruplandırarak başlayın: hangi çağrıların her ekran yükünde olduğunu, hangilerinin nadir veya arka plan olduğunu belirleyin. Bugün ne gönderdiğinizi ölçün (ortalama ve p95 yanıt boyutları ile aktif kullanıcı başına çağrı sıklığı). Sonra istemci gerçekliğini hesaba katın: düşük seviye telefonlar, kesintili ağlar, çevrimdışı davranış ve kullanıcıların ne kadar hızlı güncellediği.

Bundan sonra grup bazında seçin: okunabilirlik ve hızlı hata ayıklamanın önemli olduğu yerlerde JSON'u koruyun; boyut ve ayrıştırma hızının kanıtlanmış darboğaz olduğu yerlerde Protobuf kullanın. Son olarak küçük bir pilot çalıştırın: yüksek trafikli bir alanı değiştirin, sınırlı bir kitleye gönderin ve standartlaştırmadan önce sonuçları karşılaştırın.

Ölçtükten sonra desen genelde nettir: az sayıda uç nokta çoğu veri kullanımını ve beklemeyi sürükler. Bunlar ikili formata geçirmek için en iyi adaylardır.

Pilotta neye bakmalı

Yapıya başlamadan önce başarıyı tanımlayın. Faydalı metrikler: medyan ve p95 istek süresi, oturum başına aktarılan bayt, çökmeden arındırılmış oturum sayısı ve özellikle eski cihazlarda yanıtları ayrıştırmak için harcanan CPU zamanı.

Günde 30 kez çağrılan ve büyük listeler döndüren bir feed uç noktanız varsa Protobuf kendini amorti edebilir. Eğer en büyük sorun "neyin yanlış olduğunu söyleyemiyoruz" ise, o alan için JSON tutmak maliyetten daha fazla zaman kazandırabilir.

Ekiplerin sık yaptığı hatalar

Ekipler genelde sayıları olmadan formatlar hakkında tartışır. Bu, fazla iş ekleyip gecikme, pil kullanımı veya veri maliyetinde neredeyse değişiklik getirmeyen bir geçişle sonuçlanabilir.

Yaygın desen JSON'u Protobuf ile değiştirmek çünkü “ikili daha küçük”, sonra gerçek sorunun aşırı büyük resimler, chatty uç noktalar veya zayıf önbellekleme olduğunu keşfetmektir. Önce gerçek cihazlarda ve gerçek ağlarda ölçün, sadece hızlı ofis Wi‑Fi üzerinde değil.

Sık görülen hatalar: temel ölçüm olmadan formatı değiştirmek, küçük şema düzenlemeleri sırasında istemcileri kırmak (yeniden adlandırma, tip değişiklikleri, Protobuf alan ID'sini yeniden kullanma), her yerde gereksiz yere ikili kullanmak ve üretimde hata ayıklamayı görmezden gelmek. Bir diğer yaygın sorun ise sıkıştırma ve önbelleklemenin yanlış yapılandırılması, sonra serileştirme formatını suçlamaktır.

Pratik bir örnek: bir ekip feed uç noktasını Protobuf'a taşır ve sahte ortamda %30 daha küçük payload kutlar. Üretimde uygulama hâlâ yavaş hissediyor çünkü feed beş ayrı istek yapıyor, hiçbiri önbelleğe alınmıyor ve sunucu sürekli "her ihtimale karşı" ekstra alanlar ekliyor. Format ana sorun değildi.

Örnek senaryo: sık güncellemeleri olan bir mobil uygulama

Bir sohbet benzeri özellik olan bir mobil uygulama hayal edin: kullanıcılar bir konuşma listesini, yazıyor göstergelerini, teslim fişlerini ve ara sıra profil güncellemelerini görüyor. Mesajlar küçük, sık güncellemeler halinde geliyor ve birçok kullanıcı kesik kesik ağ bağlantısında.

JSON için tipik bir “en son güncellemeleri al” yanıtı başlangıçta küçük olur, sonra zamanla büyür. Başta sadece mesaj metni, gönderici ve zaman döner. Birkaç sürüm sonra reaksiyonlar, cihaz bazlı okunma durumları, moderasyon bayrakları ve daha zengin kullanıcı nesneleri de eklenir. JSON bunu göndermeyi kolaylaştırır, ama alan adları her öğede tekrarlandığı için payload'lar şişebilir; ekipler genelde "her ihtimale karşı" isteğe bağlı bloklar eklemeye devam eder.

{
  "messages": [
    {
      "id": "m_1842",
      "text": "On my way",
      "sentAt": "2026-01-29T10:12:03Z",
      "sender": {"id": "u_7", "name": "Maya"},
      "reactions": [{"emoji": "👍", "count": 3}],
      "readBy": ["u_2", "u_5"]
    }
  ],
  "typing": ["u_7"]
}

Protobuf ile aynı veri genelde wire üzerinde daha küçük olur çünkü alanlar sayısal etiketler ve kompakt tipler olarak kodlanır, tekrar eden stringler gönderilmez. Bu, güncellemeler sık ve kullanıcılar sınırlı veri planındaysa yardımcı olabilir. Takas koordinasyon gerektirir: şema, kod üretimi ve değişikliklerde daha sıkı kurallar gerekir. Hata ayıklama "günlükte oku"dan "doğru şema ile çözümle"ye kayar.

Yaygın sonuç bir bölünmüş yaklaşımdır. Ekipler genelde okunması sık olan ve payload'ların makul olduğu uç noktaları JSON'da tutar: giriş, ayarlar, feature flag'ler ve birçok admin ekranı. Protobuf ise yüksek hacimli trafikte (mesaj senkronizasyonu, artımlı güncellemeler, presence, yazıyor olayları ve tekrar eden nesneler içeren büyük konuşma listeleri, analiz paketleri) öne çıkar.

Eski uygulama sürümleri için güvenli bir rollout yapmak adına her şeyi bir anda çevirmeyin. Her iki formatı paralel çalıştırın (örneğin Protobuf isteyen bir header aracılığıyla), varsayılanları mantıklı tutun ve uyumluluk kurallarına sıkı bağlanın. Protobuf'ta asla alan numaralarını yeniden kullanmayın. JSON'da yeni alanları isteğe bağlı tutun ve tip değişikliklerinden kaçının.

Hızlı kontrol listesi ve sonraki adımlar

Bu kararı tad zevkine göre değil trafik ve yayın gerçeğine göre verin. Bir format seçimi yalnızca kullanıcı acısını (yavaş ekranlar, zaman aşımı, pil tükenmesi) veya ekip acısını (kırıcı değişiklikler, zor hata ayıklama) azalttığında değerdir.

Hızlı bir ön kontrol:

• Yanıtların herhangi biri düzenli olarak birkaç yüz KB'dan büyük mü veya oturum başına onlarca kez mi çağrılıyor (feed'ler, chat, izleme, sync)?
• Eski uygulama sürümleri aylarca aktif kalıyor mu?
• Her API değişikliğinde şema disiplini uygulayabilir misiniz?
• Destek ve QA, sorunları yeniden oluşturmak için payload'ları kopyalayıp yapıştırmaya ihtiyaç duyuyor mu?

Kural: payload'lar küçük ve insanlar sıkça okumak zorundaysa JSON genelde başlangıçta kazanır. Ağır, sık payload'larınız varsa ve şemaları sıkı tutabiliyorsanız Protobuf kendini amorti edebilir.

Dürüst bir sonraki adımlar planı:

1. Yoğun bir uç noktayı seçin (ana akış veya sync).
2. Aynı alanlar ve davranışla hem JSON hem Protobuf uygulayın.
3. Wire üzerindeki boyutu, orta seviye bir telefonda ayrıştırma süresini, hata oranlarını ve hata ayıklamaya harcanan zamanı ölçün.
4. Alan ekleme ve kaldırma politikası ile istemcilerin bilinmeyen alanları nasıl ele alacağını yazılı hale getirin.

Hızlı bir prototip yapmak isterseniz, AppMaster (appmaster.io) veri modelinden backend API'leri ve uygulamalar üretebilir; bu, yan yana pilot çalışması yürütmeyi ve şema değişiklikleri üzerinde elle büyük miktarda kod yazmadan yinelemeyi kolaylaştırır.