senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
veza/BACKEND_ENDPOINT_USAGE_AUDIT.md

9.7 KiB
Raw Blame History

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