Session ID Types
Understanding UUID vs Database ID formats
CRITICAL: Two Different ID Types
The API uses two different session identifiers. Using the wrong one will break your user interface or cause API errors.
Session ID UUID (Internal)
Format & Examples
39440f6c-26cb-434d-a024-14caef17f3e0
7d59781b-eeaa-4563-b40b-b7ba453391
a1b2c3d4-e5f6-7890-abcd-ef1234567890Used For
- Starting sessions
- Cancelling sessions
- Internal tracking during timer
- Anti-cheat system
❌ Display Guidelines
- Do NOT show to users
- Too long and confusing
- Not user-friendly
- Only for internal API operations
Session ID DB (User Display)
Format & Examples
123
456
789
1001Used For
- Session receipts
- User support references
- Session history
- Customer service
✅ Display Guidelines
- Always show to users
- Format as
#123 - Use monospace font
- Short and memorable
API Field Reference
Request Fields (UUID Format)
// When starting or cancelling sessions
{
"session_id": "39440f6c-26cb-434d-a024-14caef17f3e0"
}Response Fields (Database ID)
// When session is completed
{
"session_id": "123", // For display
"pomodoro": {
"id": 123 // Alternative field
}
}Implementation Examples
JavaScript/Web App
// ❌ Wrong - showing UUID to user
const sessionUuid = "39440f6c-26cb-434d-a024-14caef17f3e0";
sessionIdElement.innerHTML = `Session ID: ${sessionUuid}`; // Too long!
// ✅ Correct - showing database ID to user
const response = await fetch('/api/pomodoro/submit', { ... });
const result = await response.json();
sessionIdElement.innerHTML = `Session ID: #${result.session_id}`; // #123Swift/Mac App
// ❌ Wrong - using UUID for display
sessionIdLabel.text = "Session ID: #\(sessionUuid)" // Too long!
// ✅ Correct - using database ID for display
if let sessionId = response["session_id"] as? String {
sessionIdLabel.text = "Session ID: #\(sessionId)" // #123
}C#/Windows App
// ❌ Wrong - showing UUID
SessionIdLabel.Text = $"Session ID: #{sessionUuid}"; // Too long!
// ✅ Correct - showing database ID
SessionIdLabel.Text = $"Session ID: #{response.session_id}"; // #123Visual Comparison
❌ Bad User Experience
Session Receipt
Session ID: #39440f6c-26cb-434d-a024-14caef17f3e0
Too long, hard to read, unprofessional
Session ID: #39440f6c-26cb-434d-a024-14caef17f3e0
Too long, hard to read, unprofessional
✅ Good User Experience
Session Receipt
Session ID: #123
Short, memorable, professional
Session ID: #123
Short, memorable, professional