Choose an ID Format and Verify Its Encoding Contract
Compare UUID v7 and NanoID use cases, reproduce A → QQ== or A → 28, and distinguish byte encoding from numeric ID conversion and authentication.
Choose the identifier first and its transport representation second. UUID v7 and NanoID generate identifiers; Base64 and Base58 encode existing bytes. Encoding a value does not add randomness, compress it or make it secret.
Tools in this guide
1. Decide whether time information belongs in the ID
Use UUID v7 when a UUID-shaped identifier with a timestamp prefix fits the system. Do not use its visible order as a global event sequence: clocks can differ and multiple events can share a millisecond.
Use NanoID for a random reference with an agreed alphabet and length. Start with the URL Safe preset at length 21 for a small test batch, then size the collision risk for the application. A generated sample does not prove uniqueness at production scale.
2. Verify one byte before encoding real records
Encode the UTF-8 text A, whose byte is hexadecimal 41. Standard Base64 should produce QQ==. The Base58 tool’s alphabet 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz produces 28. Decode each and confirm A is recovered.
These encodings apply to bytes. Encoding the text 123 means encoding three characters, not converting decimal integer 123 into another number base. Record whether a field contains integer digits, text bytes or binary bytes before choosing a library.
UTF-8 text: A
Byte (hex): 41
Base64: QQ==
Base58: 283. Make the transport contract explicit
For each field, document the alphabet, padding rule, character case, maximum length and handling of leading zero bytes. Base58 has several variants; the name alone is not an interoperability contract.
The Base64 tool emits standard padded Base64; its decoder also accepts URL-safe input. If your API requires Base64url output, use an implementation that explicitly generates that format. Do not assume that a successful local decode proves the receiver accepts your chosen spelling.
4. Test rejection and round trips
Run an empty input, a known small value and a value with non-ASCII text through the producer and receiver. Compare recovered bytes, not just what the text preview happens to display. Test characters outside the permitted alphabet and length limits.
Keep a reference ID separate from an authentication secret. A URL-friendly ID is not permission to read a record. Log only the diagnostic identifiers you actually need; do not duplicate tokens or personal data in raw and encoded forms.