API Client Management System

[RichardCMX]

Overview

Implements comprehensive API client management with key registration, usage tracking, tier-based access control, and lifecycle management. Enables systematic tracking and management of API consumers with rich analytics and administrative controls.

Related Issues

Closes #31

Changes Made

🔑 Client Management System

• Client Model - Complete API consumer management

  • Basic info: name, description, contact email
  • API key management: 64-character secure keys with 8-character prefixes
  • Status lifecycle: active, inactive, suspended, revoked
  • Tier system: free, basic, premium, enterprise
  • Quotas: daily_quota, monthly_quota, rate_limit_per_minute
  • Access control: allowed_endpoints, allowed_ips (JSON fields)
  • Metadata: timestamps, created_by, last_used_at, key rotation tracking

• ClientUsage Model - Detailed usage tracking

  • Request details: endpoint, method, status_code, response_time_ms
  • Client context: user_agent, ip_address
  • Size tracking: request_size_bytes, response_size_bytes
  • Error tracking: error_message field
  • Indexed for efficient querying

🎛️ Django Admin Interface

• ClientAdmin - Comprehensive management dashboard

  • List display with status badges, usage counters, key displays
  • Advanced filtering by status, tier, creation date, last used
  • Search by name, email, key prefix, description
  • Organized fieldsets: Client Info, API Access, Quotas, Access Control, Usage Stats
  • Bulk actions: regenerate keys, activate, suspend, revoke clients
  • Real-time usage statistics (today and this month)
  • Color-coded status and last-used indicators
  • Copy-to-clipboard API key display

• ClientUsageAdmin - Read-only analytics

  • Comprehensive usage log viewing
  • Filterable by method, status code, timestamp, client tier
  • Color-coded status codes and response times
  • Date hierarchy navigation
  • Linked client references

📊 Usage Tracking

• APIUsageTrackingMiddleware - Automatic metrics collection
  • Captures all /api/* endpoint requests
  • Records response time with millisecond precision
  • Extracts client information from requests
  • Non-blocking usage capture (doesn't affect request performance)
  • Integrates with capture_api_usage() function

⚙️ Management Commands

• manage_clients - Complete client lifecycle management

  • create: Create new API clients with full configuration
  • list: Display all clients in formatted table
  • rotate-key: Regenerate API keys for security
  • activate: Activate suspended/inactive clients
  • suspend: Temporarily suspend client access
  • revoke: Permanently revoke client access
  • usage: View detailed usage statistics

• cleanup_usage - Database maintenance

  • Delete old usage records by age (default: 90 days)
  • Dry-run mode for safe testing
  • Batch processing for large datasets
  • Confirmation prompts for safety

🔐 Security Features

• Secure key generation using secrets module
• 64-character keys with mixed alphanumeric characters
• Automatic key prefix generation for identification
• Key rotation with timestamp tracking
• Optional key expiration dates
• Active status checking (status + expiration validation)
• API keys never logged or exposed in plain text
• Admin interface displays masked keys with copy functionality

📈 Analytics & Reporting

• get_usage_summary() method with period support:
  • Today's usage
  • This month's usage
  • Custom date range support
• Aggregated metrics: total requests, unique endpoints
• Integration with Django admin dashboard

Technical Implementation

• Database Migrations:

  • New Client and ClientUsage models
  • Indexes on client-timestamp, endpoint-timestamp, timestamp
  • Foreign key relationships with proper cascading
  • JSON fields for flexible access control configuration

• Middleware Integration:

  • APIUsageTrackingMiddleware registered in MIDDLEWARE setting
  • Non-intrusive request/response cycle integration
  • Automatic start time recording on request
  • Usage capture on response generation

• Admin Customization:

  • Custom admin displays with format_html for rich UI
  • QuerySet optimizations with annotations
  • Read-only fields for audit trail integrity
  • Custom actions with user feedback messages

Integration with Existing Features

• ✅ Works seamlessly with JWT authentication system
• ✅ Integrates with existing rate limiting infrastructure
• ✅ Compatible with all API endpoints (search, health, arrivals, etc.)
• ✅ Swagger UI documentation remains accessible
• ✅ No conflicts with PostgreSQL extensions (pg_trgm, unaccent)
• ✅ Usage tracking captures metrics for all protected and public endpoints

Documentation

• Updated README.md with client management section
• Updated CHANGELOG.md with comprehensive feature documentation
• Management command examples and workflows
• API key rotation procedures
• Tier and quota explanations
• Django admin feature overview

Testing Results

Found 65 test(s).
Creating test database for alias 'default'...
✓ PostgreSQL extensions installed in test database (postgis, pg_trgm, unaccent)
System check identified no issues (0 silenced).
.................................................................
----------------------------------------------------------------------
Ran 65 tests in 6.404s

OK

All existing tests pass. Client management features can be tested via Django admin and management commands.

Migration Path

1. Run migrations: python manage.py migrate
2. Create initial clients via management command or admin
3. Distribute API keys to client applications
4. Monitor usage in Django admin interface
5. Set up periodic cleanup job for usage records

Usage Examples

# Create a new client
docker-compose exec web uv run python manage.py manage_clients create \
  --name "Mobile App" \
  --email "mobile@example.com" \
  --tier premium \
  --daily-quota 10000

# List all clients
docker-compose exec web uv run python manage.py manage_clients list

# View client usage
docker-compose exec web uv run python manage.py manage_clients usage "Mobile App"

# Rotate API key
docker-compose exec web uv run python manage.py manage_clients rotate-key "Mobile App"

# Suspend a client
docker-compose exec web uv run python manage.py manage_clients suspend "Mobile App"

# Cleanup old usage records
docker-compose exec web uv run python manage.py cleanup_usage --days 90

Files Modified

• api/models.py - Added Client and ClientUsage models
• api/admin.py - Added ClientAdmin and ClientUsageAdmin
• api/middleware.py - New APIUsageTrackingMiddleware
• api/rate_limiting.py - Enhanced with capture_api_usage function
• api/management/commands/manage_clients.py - New management command
• api/management/commands/cleanup_usage.py - New cleanup command
• datahub/settings.py - Middleware and admin registration
• README.md - Client management documentation
• CHANGELOG.md - Feature documentation

Security Considerations

• API keys generated using cryptographically secure secrets module
• Keys never logged or exposed in plain text
• Status management prevents unauthorized access
• IP and endpoint restrictions available for enhanced security
• Usage tracking for audit and compliance

Performance Impact

• Middleware adds ~1-2ms per request for usage capture
• Usage records indexed for efficient querying
• Batch cleanup prevents table bloat
• Redis integration ready for distributed deployments

Backward Compatibility

• ✅ All existing API endpoints work unchanged
• ✅ No breaking changes to authentication or rate limiting
• ✅ Optional client tracking doesn't affect existing flows
• ✅ Middleware can be disabled if needed

Checklist

• Code follows project style guidelines
• All existing tests passing (65 tests)
• Documentation updated (README, CHANGELOG)
• No breaking changes
• Security best practices followed
• Database migrations included
• Management commands functional
• Django admin customizations complete

Next Steps

After merging, this branch serves as the base for:

• feature/security-performance - Additional security and performance enhancements
• feature/admin-panel-metrics - Enhanced admin panel with metrics dashboard