JSON API'de Dosya Yüklemede Base64 Kullanımı

RFC 8259’da tanımlanan JSON veri modelinin yerleşik bir ikili tipi yoktur. Her değer ya string, sayı, boolean, null, nesne ya da dizidir ve string’ler geçerli Unicode metin olmak zorundadır. Ham bir dosyanın baytları geçerli metin sayılmayan dizilimler içerebilir, dolayısıyla bunları doğrudan bir JSON string’inin içine koymanın bir yolu yoktur. Base64, ikiliyi 64 yazdırılabilir ASCII karakterden oluşan kısıtlı bir alfabeyle yeniden kodlayarak bu sorunu çözer — bir JSON string’ine, bir XML belgesine veya bir URL’ye gömülmesi güvenlidir, bedeli ise orijinal dosyadan kabaca %33 daha fazla bayttır.

Yük gerçekte nasıl görünür

Tipik bir dosya yükleme JSON gövdesi, kodlanmış veriyi sunucunun dosyayı yeniden oluşturmak için ihtiyaç duyduğu meta verilerle birlikte bir alana sarar:

{ "filename": "fatura.pdf", "contentType": "application/pdf", "data": "JVBERi0xLjQK..." }

Sunucu, alındığında data alanını ham baytlara geri çözer — kodlama adımının tam tersi — ve bunu depolamaya yazar ya da doğrudan işler. Bu desen, yalnızca JSON konuşmak isteyen webhook yüklerinde ve API istemcilerinde yaygındır, çünkü multipart yüklemelerin gerektirdiği ek content-type müzakeresinden kaçınır.

Ödünleşim: boyut ve istek sınırları

Çoğu API gateway, yük dengeleyici ve sunucu çatısı azami bir istek gövdesi boyutu dayattığından, %33’lük fazlalık gerçekte yüklenebilecek dosya boyutunu doğrudan azaltır. 10 MB ile sınırlı bir gateway, Base64-içinde-JSON yüklemelerini fiilen yaklaşık 7,5 MB gerçek dosya içeriğiyle sınırlar — kodlandıktan sonra “sınırın altında” olan bir dosyanın gerçekten geçeceğini varsaymadan önce sağlayıcınızın belgelenmiş sınırlarıyla karşılaştırmakta fayda var.

Base64'ü tamamen atlamanız gereken durumlar

Birkaç megabaytın ötesindeki her şey için, ya da istek boyutunun veya yükleme hızının gerçekten önemli olduğu her uç nokta için multipart/form-datadaha iyi bir araçtır: dosyanın ham baytlarını yalnızca küçük bir sınır işareti fazlalığıyla gönderir, %33’lük vergi yoktur. Düz HTML <input type="file"> formlarının FormData API’si üzerinden doğal olarak kullandığı yöntem de budur. JSON içinde Base64’e özellikle istemci yalnızca JSON gönderebiliyorsa, dosya küçükse ya da yükün tek bir JSON nesnesi içinde kendi kendine yetmesi gerekiyorsa başvurun — her yükleme için varsayılan yöntem olarak değil.