When designing resource URIs for an HTTP API, how do you choose between an opaque surrogate identifier such as `/users/8f3c...` and a natural key such as `/users/[email protected]` or `/products/SKU-1234`? What are the consequences of each?

## Why the URI identifier is a durable decision A URI is a name clients store: in databases, webhooks, logs, bookmarks, cached entries, and other systems' foreign references. Whatever you put in the path becomes part of your contract for as long as anyone holds it. So the question is not just readability; it is whether the identifier can be relied upon to mean the same thing forever. ## Natural keys A natural key is a domain value that already identifies the thing: an email, a username, a SKU, an ISBN, a slug. **Advantages.** Readable and self-describing in logs and support conversations. Clients can build a URL from data they already hold, avoiding a lookup round trip. For genuinely immutable, externally-governed identifiers (ISBN, ISO country code, a currency code), they are excellent — the identifier is stable because an outside authority guarantees it. **Mutability.** Most business keys are editable. A user changes their email; a product's SKU is corrected; a slug is renamed for SEO. Every stored URI is now stale. You can mitigate with permanent redirects from old keys to new, but that means keeping a forever-growing alias table and deciding what to do about a key someone else later takes. **Reuse and collision.** The dangerous case: a natural key that can be released and re-assigned. If `@alice` is freed and taken by someone else, a URI stored six months ago now resolves to a different person. Every reference — an audit log, a webhook payload, an ACL entry — silently retargets. This alone disqualifies usernames and emails as canonical identifiers in any system with real security requirements. **Encoding.** Natural keys contain characters that fight with URIs: `@`, `+`, `/`, `.`, spaces, unicode, case. `[email protected]` needs percent-encoding, and proxies, frameworks and clients disagree about decoding, especially for an encoded `%2F`. Case sensitivity is another trap: emails are commonly case-insensitive in the local part in practice, but URIs are case-sensitive, so `/users/[email protected]` and `/users/[email protected]` are two URIs for one resource unless you normalise and redirect. **Disclosure.** Putting an email or a customer name in a path leaks it into access logs, proxy logs, browser history, and `Referer` headers on outbound links. That is a privacy exposure that surrogate ids simply do not have, and it is often the point that ends the debate in a regulated environment. **Scope.** Many natural keys are unique only within a tenant or a catalogue. `/products/SKU-1234` is ambiguous the day a second seller uses the same SKU, and retrofitting scope into the path is a breaking change. ## Surrogate identifiers **Stability** is the whole point: the id is assigned at creation and never changes, so a URI stored today is valid for the resource's life regardless of any domain edit. **Neutrality** means no leakage and no encoding hazards — a UUID or a base32 ULID is URL-safe by construction. **Uniformity** simplifies routing, validation, and caching: one format to parse and reject. **Enumeration** is the risk to manage. Sequential integers advertise volume (`/orders/1041` tells a competitor your order count) and invite id-guessing. Random UUIDv4 or ULIDs remove practical enumeration, but *never* treat unguessability as authorization — object-level access control is still required on every request; an opaque id is defence in depth, not a control. **Readability** is the real cost. Mitigate with a type prefix (`cus_8f3c…`, `ord_2b19…`): it makes logs and support tickets legible, catches "customer id passed where an order id was expected" as a `400` rather than a mysterious `404`, and gives you a namespace for future migration. **Sortability** matters at scale: ULID or UUIDv7 keep creation-time ordering, which is friendlier to database index locality than UUIDv4. ## The pattern that works Make the surrogate canonical and give natural keys a first-class lookup path: ``` GET /users/usr_01HX... # canonical GET /[email protected] # filtered collection, 200 with 0 or 1 items GET /by-email/alice%40example.com # optional alias -> 301/308 to canonical ``` Using a *collection with a filter* for lookup is often cleanest: it sidesteps encoding-in-path issues (query values escape more predictably), returns `200` with an empty list rather than a `404` you must interpret, and generalises to multiple matches when the key turns out not to be unique after all. If you offer an alias path, answer with a permanent redirect so clients learn and store the canonical URI. Human-friendly slugs can coexist: `/articles/usr_01HX.../my-title` or `/articles/my-title-1041` where the numeric part is authoritative and the slug is decorative — a mismatched slug redirects to the canonical form. That gives readable URLs without making a mutable string load-bearing. ## Deciding quickly Use a natural key in the path only when it is (a) immutable, (b) never reused, (c) globally unique in your scope, (d) URL-safe, and (e) not sensitive. ISO codes and ISBNs pass. Emails, usernames, SKUs and slugs fail at least one, usually three.