2026-08-30 · 8 min read
- base64
- api-design
- performance
Embedding binary data in JSON is convenient for small values, but Base64 changes the capacity and memory model of an API. Every three input bytes generally become four characters, with padding for the final group, before property names, quotes, escaping, and transport framing are counted.
Applications may briefly hold the original bytes, encoded string, request body, parsed string, and decoded bytes at once. A payload that fits a gateway limit can still exhaust a constrained browser tab or serverless worker.
Calculate an end-to-end budget
Start from the smallest limit across browser APIs, SDKs, reverse proxies, load balancers, application frameworks, function runtimes, queues, and downstream services. Reserve room for all non-binary fields and future schema growth instead of setting the file limit equal to the request limit.
- Encoded length is four times the ceiling of input bytes divided by three.
- Data URLs add a media-type and encoding prefix.
- JSON and envelopes add keys, quotes, commas, and metadata.
- Decimal MB and binary MiB differ; state the unit explicitly.
Enforce limits before expensive work
Clients should reject oversized inputs before reading and encoding them. Servers must still enforce an encoded request limit, validate Base64 syntax, calculate the maximum decoded size, and stop decoding once a hard byte limit is reached.
Do not trust a declared length, MIME type, or filename. Validate the decoded content as required by the product, and avoid logging complete payloads on parse failures.
Move large files outside JSON
Use multipart uploads, resumable protocols, or narrowly scoped direct object-storage uploads when files exceed the small-payload budget. Streaming and chunking reduce peak memory, but require explicit integrity, retry, expiry, and partial-upload cleanup behavior.
- Bind upload authorization to object name, size, and content policy.
- Use checksums to detect corruption rather than as malware validation.
- Expire abandoned upload sessions and unreferenced objects.
- Apply downstream scanning before making content available.
Verify the deployed path
Use Flashman's Base64 tool with synthetic bytes, units converter for exact limits, JSON formatter to inspect the full wrapper, hash tool for round-trip integrity, and diff tool for truncated samples. Do not use confidential files as test fixtures.
Exercise payloads below, at, and above every boundary through the production-equivalent proxy and runtime. Capture status codes, structured errors, memory peaks, timeouts, retry behavior, and whether observability systems safely summarize failures.