Using UUIDs in APIs: Best Practices
UUIDs make excellent resource identifiers for public and internal APIs. They are opaque, stable, and reduce coupling with database details.
Design Principles
- Opaque IDs: avoid semantic meaning in IDs to prevent assumptions.
- Consistency: use the same ID format across endpoints and events.
- Validation: reject malformed UUIDs early and log failures.
Request/Response Examples
GET /v1/orders/4aa0f5c9-1b0d-4632-9b6d-8f8a9c643e1c
HTTP/1.1 200 OK
{ "id": "4aa0f5c9-1b0d-4632-9b6d-8f8a9c643e1c", "status": "paid" }
Operational Tips
- Prefer UUID v4 for simplicity; validate on ingress.
- Log IDs for tracing; redact payload secrets.
- Document ID format in API docs and SDKs.