Base64 in API Payloads: Pros, Cons, and Overhead

Base64 in API Payloads: Pros, Cons, and Overhead

Base64 encodes arbitrary binary data as printable ASCII text. It is everywhere in web development -- but often used where it should not be. Here is when to use it, when to avoid it, and what it actually costs.

How Base64 Works

Base64 takes every 3 bytes of input and encodes them as 4 ASCII characters from a 64-character alphabet (A-Z, a-z, 0-9, +, /). Padding with = when input is not a multiple of 3.

Input:   3 bytes  →  4 characters
Ratio:   33% size increase
1 MB binary  →  ~1.33 MB Base64 text

This 33% overhead is the price of ASCII compatibility.

When to Use Base64

Embedding images in JSON

{
  "avatar": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
}

JSON cannot contain raw binary. Base64 is the only option for inline binary data.

Email attachments (MIME)

SMTP is a text protocol. Every attachment is Base64-encoded in the MIME body.

Data URIs in CSS/HTML

background-image: url('data:image/svg+xml;base64,PHN2Zy...');

Small icons (< 2KB) as data URIs save an HTTP request.

JWT payloads

The header and payload of a JWT are Base64url-encoded JSON. This allows safe transport in URLs, headers, and cookies.

When NOT to Use Base64

Large files -- a 10 MB image becomes 13.3 MB as Base64 text. Use multipart/form-data for file uploads:

POST /upload
Content-Type: multipart/form-data; boundary=----

When you control both ends -- if your API client and server both handle binary, use application/octet-stream or Protocol Buffers. No encoding overhead.

Databases -- store binary in BLOB/BYTEA columns, not Base64 text. The 33% overhead compounds at scale.

URL-Safe Base64 Variant

Standard Base64 uses + and /, which have special meaning in URLs. URL-safe Base64 substitutes:

Standard:  +  /  =
URL-safe:  -  _  (padding often omitted)

Used in JWTs, OAuth tokens, and any value that travels in a URL query string.

// Node.js
const encoded = Buffer.from(data).toString('base64url');

// Python
import base64
encoded = base64.urlsafe_b64encode(data).decode()

Quick Encode/Decode

Use the Base64 tool to encode or decode strings and verify your payloads are correct before integrating them into API calls.

# Command line
echo -n 'hello world' | base64
# aGVsbG8gd29ybGQ=

echo 'aGVsbG8gd29ybGQ=' | base64 --decode
# hello world

Related