273 lines
9.7 KiB
Markdown
273 lines
9.7 KiB
Markdown
# 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
|
|
|