165 lines
3.9 KiB
Markdown
165 lines
3.9 KiB
Markdown
# Tracking API Documentation
|
|
|
|
The tracking service provides analytics about endpoint usage with time-based filtering.
|
|
|
|
## Authentication
|
|
|
|
In production, all tracking endpoints require Bearer token authentication:
|
|
```
|
|
Authorization: Bearer <your-api-token>
|
|
```
|
|
|
|
## Endpoints
|
|
|
|
### GET /api/tracking/stats
|
|
|
|
Get endpoint statistics with optional time period filtering.
|
|
|
|
**Query Parameters:**
|
|
- `period` (optional): `day`, `week`, `month`, `year`, `all` (default: `all`)
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Get all-time stats
|
|
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/stats
|
|
|
|
# Get last week's stats
|
|
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/stats?period=week
|
|
|
|
# Get last 30 days
|
|
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/stats?period=month
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"stats": [
|
|
{
|
|
"endpoint": "/",
|
|
"method": "GET",
|
|
"hit_count": 245,
|
|
"unique_users": 89,
|
|
"last_access": "2025-08-13T10:30:00Z",
|
|
"first_access": "2025-08-06T14:22:00Z"
|
|
}
|
|
],
|
|
"period": "week",
|
|
"total_endpoints": 8
|
|
}
|
|
```
|
|
|
|
### GET /api/tracking/summary
|
|
|
|
Get overall tracking summary for a time period.
|
|
|
|
**Query Parameters:**
|
|
- `period` (optional): `day`, `week`, `month`, `year`, `all` (default: `all`)
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Get today's summary
|
|
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/summary?period=day
|
|
|
|
# Get yearly summary
|
|
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/summary?period=year
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"period": "day",
|
|
"total_hits": 1247,
|
|
"total_endpoints": 12,
|
|
"total_unique_users": 234,
|
|
"oldest_visit": "2025-08-13T00:15:00Z",
|
|
"newest_visit": "2025-08-13T23:45:00Z",
|
|
"tracking_active": true
|
|
}
|
|
```
|
|
|
|
### GET /api/tracking/trends
|
|
|
|
Get visit trends over time with configurable granularity.
|
|
|
|
**Query Parameters:**
|
|
- `granularity` (optional): `hour`, `day`, `week`, `month` (default: `day`)
|
|
- `period` (optional): `24h`, `7d`, `30d`, `1y` (default: `7d`)
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Hourly trends for last 24 hours
|
|
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/trends?granularity=hour&period=24h
|
|
|
|
# Daily trends for last 30 days
|
|
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/trends?granularity=day&period=30d
|
|
|
|
# Weekly trends for last year
|
|
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/trends?granularity=week&period=1y
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"trends": [
|
|
{
|
|
"time_bucket": "2025-08-13",
|
|
"hits": 567,
|
|
"unique_users": 123,
|
|
"unique_endpoints": 8
|
|
},
|
|
{
|
|
"time_bucket": "2025-08-12",
|
|
"hits": 445,
|
|
"unique_users": 98,
|
|
"unique_endpoints": 7
|
|
}
|
|
],
|
|
"granularity": "day",
|
|
"period": "7d"
|
|
}
|
|
```
|
|
|
|
### GET /api/tracking/visits
|
|
|
|
Get recent individual visits with optional filtering.
|
|
|
|
**Query Parameters:**
|
|
- `limit` (optional): Number of visits to return (default: `50`)
|
|
|
|
**Example:**
|
|
```bash
|
|
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/visits?limit=20
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"visits": [
|
|
{
|
|
"user_hash": "a1b2c3d4e5f6...",
|
|
"endpoint": "/boxes",
|
|
"method": "GET",
|
|
"ip_address": "192.168.1.100",
|
|
"user_agent": "Mozilla/5.0...",
|
|
"referer": "https://google.com",
|
|
"timestamp": "2025-08-13T15:30:00Z"
|
|
}
|
|
],
|
|
"count": 20
|
|
}
|
|
```
|
|
|
|
## Benefits of This Approach
|
|
|
|
1. **No Duplication**: Single source of truth in `user_visits` table
|
|
2. **Flexible Querying**: Any time period can be queried on-demand
|
|
3. **Rich Analytics**: Detailed trends and user behavior insights
|
|
4. **Efficient Storage**: Only raw visits stored, stats calculated in real-time
|
|
5. **Historical Analysis**: Can analyze any historical period without pre-aggregation
|
|
|
|
## Performance Considerations
|
|
|
|
- Indexes are created on `timestamp`, `endpoint`, and `user_hash` for fast queries
|
|
- For very high traffic, consider adding materialized views for common time periods
|
|
- The SQLite database handles thousands of requests efficiently with proper indexing
|