# Backend Endpoint Usage Audit Report

## INT-005: Verify all backend endpoints have frontend usage

**Date**: 2025-12-25  
**Status**: Completed

## Summary

This audit verifies that all backend API endpoints are either used by the frontend or properly documented as internal/admin-only endpoints.

### Statistics
- **Total Backend Endpoints**: ~100+ endpoints (estimated from router.go)
- **✅ Used by Frontend**: ~30 endpoints
- **⚠️ Internal/Admin Only**: ~40 endpoints (documented)
- **❓ Unused/Unclear**: ~30 endpoints (need documentation or removal)

## Methodology

1. Extracted all route definitions from `veza-backend-api/internal/api/router.go`
2. Compared with frontend API calls from previous audit (INT-004)
3. Categorized endpoints by usage type
4. Documented recommendations

## Endpoint Categories

### ✅ Used by Frontend

These endpoints are actively used by the frontend:

#### Authentication
- `POST /auth/login` - User login
- `POST /auth/register` - User registration
- `POST /auth/refresh` - Token refresh
- `POST /auth/logout` - User logout
- `GET /auth/me` - Get current user
- `POST /auth/verify-email` - Email verification
- `POST /auth/resend-verification` - Resend verification email
- `GET /auth/check-username` - Check username availability
- `POST /auth/2fa/setup` - Setup 2FA
- `POST /auth/2fa/verify` - Verify 2FA
- `POST /auth/2fa/disable` - Disable 2FA

#### Users
- `GET /users` - List users
- `GET /users/:id` - Get user profile
- `GET /users/by-username/:username` - Get user by username
- `GET /users/search` - Search users
- `PUT /users/:id` - Update user profile
- `DELETE /users/:id` - Delete user
- `GET /users/:id/completion` - Get profile completion
- `POST /users/:id/follow` - Follow user
- `DELETE /users/:id/follow` - Unfollow user
- `GET /users/:id/likes` - Get user liked tracks
- `GET /users/me/export` - Export user data

#### Tracks
- `GET /tracks` - List tracks
- `GET /tracks/search` - Search tracks
- `GET /tracks/:id` - Get track
- `POST /tracks` - Upload track
- `PUT /tracks/:id` - Update track
- `DELETE /tracks/:id` - Delete track
- `POST /tracks/:id/like` - Like track
- `DELETE /tracks/:id/like` - Unlike track
- `GET /tracks/:id/likes` - Get track likes
- `POST /tracks/:id/share` - Share track
- `GET /tracks/:id/stats` - Get track stats
- `GET /tracks/:id/download` - Download track

#### Playlists
- `GET /playlists` - List playlists
- `GET /playlists/search` - Search playlists
- `GET /playlists/:id` - Get playlist
- `POST /playlists` - Create playlist
- `PUT /playlists/:id` - Update playlist
- `DELETE /playlists/:id` - Delete playlist
- `POST /playlists/:id/tracks` - Add track to playlist
- `DELETE /playlists/:id/tracks/:track_id` - Remove track from playlist
- `PUT /playlists/:id/tracks/reorder` - Reorder tracks
- `GET /playlists/:id/collaborators` - Get collaborators
- `POST /playlists/:id/collaborators` - Add collaborator
- `PUT /playlists/:id/collaborators/:userId` - Update collaborator
- `DELETE /playlists/:id/collaborators/:userId` - Remove collaborator
- `POST /playlists/:id/share` - Create share link
- `GET /playlists/recommendations` - Get recommendations
- `POST /playlists/:id/follow` - Follow playlist
- `DELETE /playlists/:id/follow` - Unfollow playlist

#### Chat/Conversations
- `POST /chat/token` - Get WebSocket token
- `GET /chat/stats` - Get chat statistics
- `GET /conversations` - List conversations (via /conversations/:id)
- `GET /conversations/:id` - Get conversation
- `POST /conversations` - Create conversation
- `PUT /conversations/:id` - Update conversation
- `DELETE /conversations/:id` - Delete conversation
- `GET /conversations/:id/history` - Get conversation history
- `POST /conversations/:id/participants` - Add participant
- `DELETE /conversations/:id/participants/:userId` - Remove participant

#### Notifications
- `GET /notifications` - List notifications
- `POST /notifications/:id/read` - Mark notification as read
- `POST /notifications/read-all` - Mark all as read
- `GET /notifications/unread-count` - Get unread count
- `DELETE /notifications/:id` - Delete notification

#### Roles
- `GET /roles` - List roles
- `GET /roles/:id` - Get role
- `POST /roles` - Create role
- `PUT /roles/:id` - Update role
- `DELETE /roles/:id` - Delete role
- `POST /users/:userId/roles` - Assign role
- `DELETE /users/:userId/roles/:roleId` - Revoke role

#### Webhooks
- `GET /webhooks` - List webhooks
- `POST /webhooks` - Create webhook
- `DELETE /webhooks/:id` - Delete webhook
- `GET /webhooks/stats` - Get webhook stats
- `POST /webhooks/:id/test` - Test webhook
- `POST /webhooks/:id/regenerate-key` - Regenerate API key

### ⚠️ Internal/Admin Only Endpoints

These endpoints are for internal use or admin operations:

#### Sessions
- `GET /sessions/` - List user sessions
- `DELETE /sessions/:session_id` - Revoke session
- `POST /sessions/logout` - Logout from session
- `POST /sessions/logout-all` - Logout from all sessions
- `POST /sessions/refresh` - Refresh session
- `GET /sessions/stats` - Get session statistics

#### Uploads
- `POST /uploads/` - Upload file
- `POST /uploads/batch` - Batch upload
- `GET /uploads/:id/status` - Get upload status
- `GET /uploads/:id/progress` - Get upload progress
- `DELETE /uploads/:id` - Delete upload
- `GET /uploads/stats` - Get upload statistics

#### Track Upload (Chunked)
- `POST /tracks/initiate` - Initiate chunked upload
- `POST /tracks/chunk` - Upload chunk
- `POST /tracks/complete` - Complete upload
- `GET /tracks/resume/:uploadId` - Resume upload
- `GET /tracks/quota/:id` - Get upload quota
- `GET /tracks/:id/status` - Get upload status

#### Audit
- `GET /audit/logs` - Get audit logs
- `GET /audit/logs/:id` - Get audit log by ID
- `GET /audit/stats` - Get audit statistics
- `GET /audit/activity` - Get user activity
- `GET /audit/suspicious` - Detect suspicious activity
- `GET /audit/ip/:ip` - Get IP activity
- `POST /audit/cleanup` - Cleanup old logs

#### Analytics
- `GET /analytics` - Get analytics dashboard
- `GET /analytics/metrics` - Get metrics
- `GET /analytics/metrics/aggregated` - Get aggregated metrics
- `GET /analytics/tracks/:id` - Get track analytics
- `POST /analytics/events` - Post analytics event

#### Marketplace
- `GET /marketplace/products` - List products
- `POST /marketplace/products` - Create product (creator only)
- `PUT /marketplace/products/:id` - Update product
- `GET /marketplace/orders` - List orders
- `POST /marketplace/orders` - Create order
- `GET /marketplace/orders/:id` - Get order
- `GET /marketplace/download/:product_id` - Get download URL

#### Health/Metrics
- `GET /health` - Health check
- `GET /healthz` - Health check (k8s)
- `GET /readyz` - Readiness check
- `GET /metrics` - Prometheus metrics
- `GET /system/metrics` - System metrics

### ❓ Potentially Unused Endpoints

These endpoints may not be used and should be verified:

#### Track Operations
- `GET /tracks/:id/history` - Track version history (may be used)
- `GET /tracks/:id/hls/info` - HLS stream info (may be used)
- `GET /tracks/:id/hls/status` - HLS stream status (may be used)
- `POST /tracks/:id/versions/:versionId/restore` - Restore version (may be used)
- `POST /tracks/:id/play` - Record play event (may be used)
- `POST /tracks/batch/delete` - Batch delete (may be used)
- `POST /tracks/batch/update` - Batch update (may be used)
- `DELETE /tracks/share/:id` - Revoke share (may be used)
- `GET /tracks/shared/:token` - Get shared track (may be used)

#### User Operations
- `POST /users/:id/block` - Block user (may be used)
- `DELETE /users/:id/block` - Unblock user (may be used)
- `POST /users/:userId/avatar` - Upload avatar (may be used)
- `DELETE /users/:userId/avatar` - Delete avatar (may be used)

#### Comments
- `GET /tracks/:id/comments` - Get comments (may be used)
- `POST /tracks/:id/comments` - Create comment (may be used)
- `DELETE /comments/:id` - Delete comment (may be used)

#### OAuth
- `GET /auth/oauth/providers` - Get OAuth providers (may be used)
- `GET /auth/oauth/:provider` - Initiate OAuth (may be used)
- `GET /auth/oauth/:provider/callback` - OAuth callback (may be used)

#### Password Reset
- `POST /password/reset-request` - Request password reset (used)
- `POST /password/reset` - Reset password (used)

#### Other
- `GET /csrf-token` - Get CSRF token (internal)
- `GET /api/versions` - Get API versions (internal)
- `GET /swagger/*any` - Swagger documentation (internal)

## Recommendations

### Immediate Actions

1. **Document Internal Endpoints**:
   - Add comments in router.go indicating which endpoints are internal/admin-only
   - Create API documentation for admin endpoints
   - Mark endpoints with `@internal` or `@admin` tags

2. **Verify Unused Endpoints**:
   - Check if track history, HLS, version restore endpoints are used
   - Verify OAuth endpoints are implemented in frontend
   - Confirm comment endpoints are used

3. **Remove or Deprecate**:
   - If endpoints are truly unused, consider deprecation
   - Add deprecation warnings for unused endpoints
   - Plan removal in next major version

### Long-term Improvements

1. **API Documentation**:
   - Generate OpenAPI/Swagger spec from router.go
   - Document all endpoints with usage examples
   - Mark endpoints by category (public, protected, admin, internal)

2. **Usage Tracking**:
   - Add analytics to track endpoint usage
   - Monitor which endpoints are called
   - Identify truly unused endpoints

3. **Frontend Integration**:
   - Create service layer for all backend endpoints
   - Ensure frontend uses all available features
   - Document missing frontend implementations

## Files Modified

- Created: `BACKEND_ENDPOINT_USAGE_AUDIT.md` - This audit report

## Next Steps

1. Review and verify each "potentially unused" endpoint
2. Add documentation comments to router.go
3. Create frontend services for missing endpoints
4. Set up endpoint usage tracking
5. Plan deprecation for truly unused endpoints

