UUID in REST APIs — Best Practices

Published by UUID Generator Team

Using UUIDs in REST APIs gives stable, non-guessable resource IDs. Here are practical guidelines for paths, headers, and responses.

URLs and Paths

Use the canonical form with hyphens: /users/550e8400-e29b-41d4-a716-446655440000. UUIDs are safe in paths (no reserved characters). Accept lowercase; normalize before lookup if you store in lowercase. Return 404 for invalid or unknown UUIDs and 400 if the client sends a malformed ID in the path or body.

Request and Response Bodies

Represent UUIDs as strings in JSON: "id": "550e8400-e29b-41d4-a716-446655440000". Don't strip hyphens unless you have a strong reason; the standard format is widely supported. Validate incoming UUIDs (format and, if applicable, existence) before using them. Use our validation API (GET /api/validate/{uuid} or POST /api/validate-bulk) or your own regex.

Headers

If you use UUIDs in headers (e.g. request or correlation IDs), keep the same string format. Document whether you accept only lowercase or both cases and whether hyphens are required.

Summary

Use canonical UUID strings in paths and JSON; validate on input; return clear errors for invalid IDs. Generate UUIDs with our generator or API; validate with our validator or API.

How to validate a UUID · API docs · Home