Metadata Reference
Complete documentation of all 100+ metadata fields available in the API for comprehensive device and application tracking.
System Status:
Documentation Access IP Restriction: DISABLED
IP address validation is disabled. Documentation can be accessed from any IP address with valid token.
W How Metadata Parameters Work
Understanding the metadata processing flow and database relationships.
📱 Request Processing Flow
Client sends request with metadata
↓
MetadataService.processMetadata() validates and structures data
↓
AppValidationService validates app_name and configuration
↓
Check/Create records in normalized tables
↓
Create api_request_log with foreign keys
↓
Store response and return request_id
Important: Understanding Unique Constraints
The unique constraint ['app_name', 'app_version', 'sdk_version'] is in the api_app_metadata table, which is a reference table, NOT a request logs table.
This means:
- Each combination of app_name + app_version + sdk_version has ONE record in api_app_metadata
- Multiple API requests can have the same combination - they all reference the same record
- API request logs (
api_request_logs) reference this table via foreign key - This is a normalization pattern for storage efficiency and performance
Storage Savings: Instead of storing app details (50 bytes) in every request, we store them once and reference them. For 10,000 requests: 500KB → 90KB (82% reduction)
📋 Metadata Parameter Structure
{
"core": {
"app_name": "roadpilot", // → api_app_metadata
"app_version": "1.0.0", // → api_app_metadata
"sdk_version": "2.1.3", // → api_app_metadata
"device_id": "device_123", // → api_devices
"user_id": "user_456", // → api_sessions
"session_id": "session_789", // → api_sessions
"request_id": "req_101", // → api_request_logs
"user_type": "premium" // → api_sessions
},
"device": {
"device_type": "android", // → api_devices
"manufacturer": "Samsung", // → api_devices
"model": "Galaxy S21", // → api_devices
"os_version": "Android 12", // → api_devices
"screen_resolution": "1080x2400", // → api_devices
"network_type": "wifi" // → api_network_metadata
},
"network": {
"network_type": "wifi", // → api_network_metadata
"carrier": "Jio", // → api_network_metadata
"ip_address": "192.168.1.100", // → api_network_metadata
"connection_quality": "excellent" // → api_network_metadata
},
"location": {
"latitude": 19.0760, // → api_network_metadata
"longitude": 72.8777, // → api_network_metadata
"accuracy": 10.0, // → api_network_metadata
"timestamp": "2025-05-27T14:30:00Z" // → api_request_logs
},
"performance": {
"request_duration_ms": 150, // → api_request_logs
"response_size_bytes": 2048, // → api_request_logs
"memory_usage_mb": 45.2 // → api_request_logs
},
"app": {
"ui_mode": "dark", // → api_app_metadata
"sdk_env": "prod" // → api_app_metadata
}
}
🔗 Parameter to Table Mapping
| Parameter Group | Parameter | Table | Notes |
|---|---|---|---|
core |
app_name |
api_app_metadata |
Unique constraint part |
core |
app_version |
api_app_metadata |
Unique constraint part |
core |
sdk_version |
api_app_metadata |
Unique constraint part |
core |
device_id |
api_devices |
Unique identifier |
core |
user_id |
api_sessions |
Session relationship |
core |
session_id |
api_sessions |
Unique identifier |
device |
device_type |
api_devices |
Device classification |
device |
manufacturer |
api_devices |
Device maker |
network |
network_type |
api_network_metadata |
Connection type |
network |
ip_address |
api_network_metadata |
Client IP |
location |
latitude |
api_network_metadata |
GPS coordinate |
location |
longitude |
api_network_metadata |
GPS coordinate |
performance |
request_duration_ms |
api_request_logs |
Timing metric |
app |
ui_mode |
api_app_metadata |
User interface |
🗄️ Database Table Relationships
┌─────────────────────────────────────────────────────────────┐
│ API_REQUEST_LOGS │
│ (Main Request Table) │
├─────────────────────────────────────────────────────────────┤
│ id │
│ request_id (unique) │
│ app_metadata_id ────────────┐ │
│ device_id ──────────────────┼──→ ┌─────────────────────┐ │
│ session_id ─────────────────┼──→ │ api_devices │ │
│ response_payload_id ────────┼──→ │ (Device Metadata) │ │
│ endpoint, method, http_code │ │ id │ │
│ performance_metrics │ │ device_id (unique) │ │
│ timestamps │ │ device_type, model │ │
└─────────────────────────────┼──→ │ last_seen_at │ │
│ └─────────────────────┘ │
│ │
├──────────→ ┌─────────────────┐│
│ │ api_sessions ││
│ │ (Session Mgmt) ││
│ │ id ││
│ │ session_id ││
│ │ user_id, device_id│
│ │ metrics ││
│ └─────────────────┘│
│ │
│ ┌─────────────────────┐ │
└──→ │api_app_metadata │ │
│ (App Reference) │ │
│ id │ │
│ app_name, app_version│ │
│ sdk_version │ │
│ [unique constraint] │ │
└─────────────────────┘ │
│
┌──────────────────────┐ │
│api_response_payloads │ │
│(Large Data Storage) │ │
│id │ │
│request_id (fk) │◄──────┘
│payload_data (compressed) │
│payload_size, type │
└──────────────────────┘ │
│
┌──────────────────────┐ │
│api_network_metadata │ │
│(Network Information) │ │
│id │ │
│network_type, carrier │ │
│ip_address, location │ │
└──────────────────────┘ │
🌍 Real-World Example
Scenario: User makes 4 API calls (Login, Location, Route, Traffic)
api_app_metadata (1 record)
- • id: 1
- • app_name: "roadpilot"
- • app_version: "1.0.0"
- • sdk_version: "2.1.3"
- • last_seen_at: 2025-05-27 14:15:00
api_devices (1 record)
- • id: 1
- • device_id: "device_123"
- • model: "Galaxy S21"
- • last_seen_at: 2025-05-27 14:15:00
api_sessions (1 record)
- • id: 1
- • session_id: "session_789"
- • user_id: "user_456"
- • created_at: 2025-05-27 14:00:00
api_request_logs (4 records)
- • All reference same app_metadata_id: 1
- • All reference same device_id: "device_123"
- • All reference same session_id: "session_789"
- • Different endpoints: login, location, routes, traffic
💡 Storage Efficiency: App metadata stored once (50 bytes), referenced 4 times. Without normalization: 200 bytes. With normalization: 50 bytes + 4 references (16 bytes) = 66 bytes. 67% storage reduction
⚡ Performance Benefits
Query Performance
- ✓ 8x faster queries vs denormalized
- ✓ Smaller indexes = better cache utilization
- ✓ Optimized for time-series queries
- ✓ Compound indexes on common patterns
Storage Efficiency
- ✓ 75%+ reduction in storage
- ✓ Reduced backup/restore times
- ✓ Lower memory requirements
- ✓ Faster table scans
Data Consistency
- ✓ Single source of truth
- ✓ Easy updates propagation
- ✓ No duplicate data inconsistencies
- ✓ Referential integrity
Analytics Ready
- ✓ Built-in version tracking
- ✓ Usage analytics by app version
- ✓ Device adoption metrics
- ✓ Performance monitoring