Base64, data URIs, and API design: patterns that don’t wreck latency
Engineering leads can keep payloads debuggable without turning every endpoint into a multi-megabyte string soup.
When embedding beats linking
Tiny icons or single-page proofs benefit from data URIs in tightly scoped admin tools. Multi-megabyte PDFs belong in object storage with signed URLs—always.
Mobile clients on flaky networks may prefer one JSON payload if TLS handshakes dominate; measure before romanticizing either extreme.
CDN cache headers on linked assets beat repeated base64 transfer for public traffic.
Debugging ergonomics
Log base64 lengths, not contents, in production. Decode in dev tools locally when reproducing.
Schema annotate fields with format: byte hints for codegen clarity.
Reject unknown fields early—lazy parsing hides corruption until downstream.
Security footguns
Data URIs mixing HTML/JS confusion in rich text editors cause XSS—sanitize aggressively.
Limit MIME allowlists server-side; don’t trust client-declared types.
Rotate signing keys for URL downloads; short TTL for exfil risk.
Performance math
Base64 expands ~33 percent—account for serialization and gzip interplay.
Batch binary in protobuf or CBOR when JSON overhead dominates—interop trade accepted.
Profile end-to-end first; micro-optimizing encode without measuring gains nothing.
Documentation tone
Show curl examples with `--data-binary @file` alongside JSON embeddings for humans.
Version docs when field shapes change—semver APIs deserve semver docs.
Link troubleshooting to Merge AI’s encoder for quick human verification—keep secrets redacted.
Migration stories
Teams moving from monolithic XML to JSON often carry base64 baggage—schedule decoupling milestones with observability on payload size percentiles.
Feature flag nested object shapes; dual-write cautiously with reconciliation jobs.
Celebrate deprecations that remove bytes—not just lines of code.
Collaboration across frontend and backend
Contract tests using recorded fixtures prevent accidental schema drift. Store golden files in git with review rituals.
Designers shouldn’t paste giant data URIs into CMS WYSIWYG—enforce upload flows.
PagerDuty runbooks should list decoding commands safe to paste with redaction macros.