Sending Binary Data in JSON APIs with Base64

Published: 2025-12-03 | Category: Web/API

The JSON Binary Problem

JSON (JavaScript Object Notation) is the undisputed standard for data exchange in modern REST and GraphQL APIs. However, JSON has a severe limitation: it is a text-only format. It natively supports strings, numbers, booleans, and null, but it absolutely cannot handle raw binary bytes.

If your application needs to upload a user avatar, download a generated PDF invoice, or sync an audio file via a JSON API, you are faced with an architectural challenge. The most common solution is to Base64 encode the binary file.

How Base64 Solves the Problem

By running a binary file through a Base64 encoder, you translate all the unprintable bytes into a safe, standard ASCII string. This string can easily be assigned to a JSON key.

{
  "userId": 1024,
  "action": "UPDATE_AVATAR",
  "imageFormat": "png",
  "imageData": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
}

The server receives the JSON, parses it, extracts the imageData string, and runs it through a Base64 decoder to reconstruct the original PNG file on disk.

The Performance Penalty

While embedding Base64 in JSON is incredibly convenient for developers (avoiding complex multipart/form-data parsing), it comes with severe performance penalties that system architects must consider:

1. The 33% Network Tax

Because Base64 uses 4 characters (32 bits) of text to represent 3 bytes (24 bits) of raw data, it mathematically inflates the size of the payload by 33.3%. A 3MB photograph becomes a 4MB JSON payload. While HTTP compression (gzip/Brotli) can mitigate this slightly, it still increases network transfer times.

2. Memory and CPU Overhead

JSON parsers (like JSON.parse() in JavaScript) must load the entire string into memory to build the Abstract Syntax Tree. If you include a 15MB Base64 video file in a JSON response, the browser must allocate a massive chunk of RAM on the main thread, leading to UI freezing and high Time to Interactive (TTI) metrics.

Best Practices for API Design

Given the performance costs, when should you use Base64 in JSON?

Micro-Assets Only: It is perfectly acceptable to use Base64 for tiny files (under 100KB), such as small avatar thumbnails, signature captures, or short voice clips.
Use Presigned URLs for Large Files: For large files (PDFs, videos, high-res images), the JSON API should not return the file data directly. Instead, the API should return a temporary, presigned URL (e.g., to an AWS S3 bucket) that the client can use to download the raw binary file directly.
Consider Multipart Form Data: For uploads, standard multipart/form-data HTTP requests allow you to stream the binary file efficiently alongside metadata, completely avoiding the Base64 inflation tax.