Best Practices for UUIDs in URLs

UUID Format Conventions in URLs

When using UUID in URLs, follow these format conventions: always use lowercase (RFC 4122 recommended, and maintains consistency when URLs are case-sensitive); keep hyphens (standard UUID format, improving readability and recognizability); don't add curly braces ({} are illegal URL characters requiring encoding as %7B%7D, increasing URL length and complexity); UUIDs should appear only in path parameters, not as query parameters (unless business truly requires it). For example: /api/users/550e8400-e29b-41d4-a716-446655440000 is the correct format.

SEO Impact of UUID in URLs

For SEO-oriented content pages, using UUID directly in URLs is not ideal. Pure UUID URLs (like /articles/550e8400-e29b-41d4-a716-446655440000) contain no semantic information; search engines cannot infer page content from the URL, and they are difficult for users to remember and share. Better approaches: for SEO-facing public pages, use a slug (short descriptive string) as the URL component, using UUID only for APIs and internal systems; or adopt a slug + UUID hybrid format (like /articles/how-to-generate-uuid-550e8400), providing both SEO-friendliness and uniqueness guarantee; for pure APIs (no SEO requirements), UUID URLs are perfectly appropriate.

Routing Design Patterns

# 典型路由模式示例

# 模式1：纯 UUID（API 路由，推荐用于内部/后端）
/api/v1/users/550e8400-e29b-41d4-a716-446655440000
/api/v1/orders/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

# 模式2：slug + UUID 混合（公开 URL，SEO + 唯一性）
/blog/how-to-generate-uuid-550e8400e29b
# 仅取 UUID 前 12 字符用于去重标识

# 模式3：slug 只（纯 SEO，需要数据库确保 slug 唯一）
/blog/how-to-generate-uuid

# 模式4：短码（用户友好，适合邀请链接等）
/invite/abc123def
# 使用 NanoID 生成 8-12 字符短码

# Django URL 路由配置
from django.urls import path, re_path
import uuid

urlpatterns = [
    # 类型安全：Django 自动验证 UUID 格式
    path('api/users/<uuid:user_id>/', views.user_detail),

    # 正则方式（更灵活）
    re_path(r'^api/items/(?P<item_id>[0-9a-f-]{36})/$', views.item_detail),
]

Case Sensitivity Issues

The HTTP specification states that URL paths are case-sensitive, meaning /users/550E8400-... and /users/550e8400-... are technically different URLs. To avoid confusion from case issues: on the server side, normalize all UUID path parameters to lowercase before processing; return 301 redirects for uppercase UUID URLs to their lowercase versions (maintaining canonicality); in client code, always generate and pass UUIDs in lowercase; in databases, UUID comparisons should use case-insensitive methods (or store consistently as lowercase). This avoids the awkward situation of "record exists in database but uppercase URL returns 404."

UUID Security Considerations in URLs

Exposing UUID in URLs has several security considerations: UUIDs appear in HTTP Referer headers and may be exposed to third-party resources (when images and scripts are loaded, they carry the current page URL); UUIDs appear in browser history, log systems, and CDN logs; for sensitive resources (like private file download links), UUIDs serve as "capability URLs" providing some protection, but should have an access control layer (don't grant access based on UUID knowledge alone); you can add time limits to sensitive UUID URLs (with signatures or expiry times), like GitHub's blob download links.

Using UUID Without Hyphens in URLs

Some developers use compact UUID without hyphens (32 characters) in URLs to shorten URL length. This is acceptable, but note: no-hyphen format is less intuitive in URLs (difficult to immediately recognize as UUID); if mixing hyphenated and non-hyphenated formats, normalization is needed at the routing level; it's recommended to clearly specify in API documentation which format is used to avoid caller confusion. Another option is encoding UUID's 128 bits with Base64 or Base58, getting a shorter (22-character Base64 or 22-character Base58) but equally informative ID.