Base64 in APIs: When It Helps and When It Hurts
Base64 makes binary safe for JSON - and inflates payloads by ~33%. Here’s when encoding earns its keep and when you should send raw bytes instead.
Part of the Technical Foundations series.
Base64 shows up in API reviews like cilantro: some teams put it in everything, others refuse it on sight. Both instincts are incomplete. Encoding is a tool for a specific constraint - usually “I must stuff binary into a text channel.”
When Base64 helps
- JSON fields that must carry small binaries - icons, short signatures, tiny protobufs - without multipart complexity.
- Tokens and wire formats that defined it - JWT parts are Base64URL by design. Don’t invent a parallel scheme.
- Config files and feature flags that only accept text.
- Debug transport - pasting a blob into a ticket after local encoding (still mind privacy).
Encode and decode locally with Base64 Encoder and Base64 Decoder. Prefer URL-safe Base64 when values land in paths or query strings. Related workflow: format, minify, and Base64 privately.
When Base64 hurts
- Large files. You pay ~33% size overhead before HTTP compression. Multipart uploads or blob storage URLs usually win.
- Hot paths. Encode/decode CPU adds up at scale for multi-megabyte bodies.
- Double encoding. Base64 inside Base64, or UTF-8 strings unnecessarily encoded, wastes everyone’s day.
- Security cosplay. Base64 is not encryption. Obscuring a secret in Base64 is a delay for humans, not protection.
API design notes
- Document whether fields are standard Base64 or Base64URL (different alphabets, different padding rules).
- Cap accepted sizes explicitly.
- Consider sending
content-typealongside encoded blobs so clients know how to interpret bytes after decode. - For downloads, return raw bytes with proper content types instead of JSON wrappers when clients are apps, not browsers stuck with JSON.
Checklist before you add a Base64 field
- Is there a binary-friendly alternative (multipart, separate URL)?
- What’s the p99 payload size after the 33% bump?
- Do we validate decode errors cleanly?
- Are we accidentally encouraging secrets-in-JSON?
Validate suspicious strings with Base64 Validator during debugging, and keep production secrets out of online toys - same privacy instinct as the rest of this wave.
Size math you can do on a napkin
Raw bytes R become roughly ceil(4 * ceil(R / 3)) characters in Base64, plus padding. A 3 MB PDF becomes about 4 MB of text before headers. If your JSON API also pretty-prints, logs grow fast. Gateways with body limits start failing in ways that look like client bugs.
When payloads cross a few hundred kilobytes regularly, revisit the design. Object storage plus a short-lived URL inside JSON is usually kinder.
Security footguns
- Logging Base64 fields that contain personal photos or IDs.
- Accepting unbounded Base64 in public endpoints (easy CPU DoS).
- Thinking HTTPS + Base64 equals confidentiality beyond transport - it doesn’t.
Decode only after authz checks. Reject once decoded size exceeds your limit, not only at character count if you can help it.
Client libraries
Provide helpers that encode correctly (URL-safe vs standard) so app developers don’t hand-roll bugs. Document examples for each. A five-line sample prevents months of support about padding = characters in URLs.
Field notes from teams who shipped this
The pattern that keeps showing up: write the constraint first, then the steps, then the failure modes. Teams that only publish happy-path screenshots create tickets. Teams that document the ugly path create trust.
Schedule a short review ninety days after publishing. Check whether product UI names still match, whether linked tools still exist, and whether support still hears the same questions. Update the page or merge it. Standing still is how useful posts become interchangeable again.
If you adapt this article for internal wikis, keep the examples tied to your stack names. The moment you generalize back to “best practices for organizations,” you’ve started erasing the specificity that made the piece worth saving.
Observability with encoded fields
APM tools love to capture payloads. Base64 blobs blow up trace storage and can leak sensitive binaries into log lakes. Configure redaction for known encoded fields. Sample carefully.
Metrics should track payload sizes pre- and post-decode where feasible so you notice growth trends before gateways start 413-ing clients.
When exposing public APIs, publish explicit examples for encode/decode in more than one language. Ambiguity about URL-safe alphabets creates incompatible clients that all think they’re right.
If you decide to remove a Base64 field in v2, provide a download URL alternative and a long deprecation window - mobile clients change slowly.
Migrating off Base64 fields
Add the new URL-based field beside the old encoded field. Teach clients to prefer the URL. Track usage metrics. Remove Base64 only after usage falls below an explicit threshold. Surprise breakages on encoded fields are nasty because error messages often look like JSON schema failures rather than deprecations.
Announce in changelogs with a decode tip for lagging clients.
FAQ
Does gzip erase the size penalty?
It recovers some of it, not all, and you still pay encode/decode CPU and memory spikes.
Are data-URIs okay in APIs?
They’re Base64 with a header fancy dress - fine for tiny assets, miserable for large media.