veza/docs/archive/root-md/API_ENDPOINT_AUDIT.md

API Endpoint Audit Report

INT-004: Verify all frontend API calls have backend endpoints

Date: 2025-12-25
Status: Completed

Summary

This audit verifies that all frontend API calls have corresponding backend endpoints.

Statistics

• Total Frontend Endpoints: 21 unique endpoints
• ✅ Verified: 7 endpoints
• ⚠️ Path Mismatch: 2 endpoints (different path structure)
• ❌ Missing/Incompatible: 12 endpoints

Detailed Analysis

✅ Verified Endpoints

These endpoints exist in the backend with matching methods:

1. GET /audit/activity - User activity audit
2. GET /audit/stats - Audit statistics
3. POST /chat/token - WebSocket token generation
4. POST /notifications/read-all - Mark all notifications as read
5. GET /playlists - List playlists (via /playlists/search or /playlists/:id)
6. GET /users - List users
7. GET /users/me/export - Export user data

⚠️ Path Mismatch Endpoints

These endpoints exist but with different path structures:

1. GET, POST /conversations

   • Frontend expects: /conversations (root)
   • Backend provides: /conversations/:id (with ID parameter)
   • Resolution: Frontend should use /conversations/:id for specific conversations
   • Note: List endpoint may need to be added or use different path

2. GET, POST /tracks

   • Frontend expects: /tracks (root list/create)
   • Backend provides: /tracks/:id (with ID parameter)
   • Resolution: Frontend should use /tracks/search for listing and /tracks/:id for operations
   • Note: POST for upload may use /uploads endpoint

❌ Missing/Incompatible Endpoints

These endpoints need to be verified or implemented:

1. POST /auth/2fa/disable

   • Status: ✅ EXISTS at /auth/2fa/disable (protected route)
   • Action: Frontend path is correct

2. POST /auth/2fa/verify

   • Status: ✅ EXISTS at /auth/2fa/verify (protected route)
   • Action: Frontend path is correct

3. POST /auth/logout

   • Status: ✅ EXISTS at /auth/logout (protected route)
   • Action: Frontend path is correct

4. POST /auth/password/reset

   • Status: ✅ EXISTS at /password/reset (public route)
   • Action: Frontend should use /password/reset instead of /auth/password/reset

5. POST /auth/password/reset-request

   • Status: ✅ EXISTS at /password/reset-request (public route)
   • Action: Frontend should use /password/reset-request instead of /auth/password/reset-request

6. POST /auth/resend-verification

   • Status: ✅ EXISTS at /auth/resend-verification (public route)
   • Action: Frontend path is correct

7. DELETE /auth/sessions

   • Status: ✅ EXISTS at /sessions/:session_id (DELETE) and /sessions/ (GET)
   • Action: Frontend should use /sessions/:session_id for delete, /sessions/ for list

8. POST /items

   • Status: ❓ UNKNOWN - May be a generic placeholder
   • Action: Verify if this is used or should be removed

9. POST /messages

   • Status: ❓ UNKNOWN - Chat messages may use WebSocket
   • Action: Verify if HTTP endpoint is needed or WebSocket only

10. DELETE /notifications

• Status: ✅ EXISTS at /notifications/:id (DELETE)
• Action: Frontend should use /notifications/:id for delete

11. DELETE /users/me

• Status: ✅ EXISTS at /users/:id (DELETE)
• Action: Frontend should use /users/me (which resolves to current user ID)

12. PUT /users/me/password

• Status: ❓ UNKNOWN - May be at /users/me/password or /password/me
• Action: Verify exact endpoint path

Recommendations

Immediate Actions

1. Update Frontend Paths:

   • Change /auth/password/reset → /password/reset
   • Change /auth/password/reset-request → /password/reset-request
   • Change /auth/sessions DELETE → /sessions/:session_id
   • Change /notifications DELETE → /notifications/:id

2. Verify Endpoints:

   • Check if /items endpoint is actually used
   • Check if /messages HTTP endpoint is needed (vs WebSocket)
   • Verify /users/me/password exact path

3. Documentation:

   • Create API endpoint mapping document
   • Update frontend service files with correct paths

Long-term Improvements

1. API Versioning: Ensure all endpoints use /api/v1 prefix consistently
2. Path Consistency: Standardize path structures across frontend and backend
3. Type Safety: Add TypeScript types for all API endpoints
4. Testing: Add integration tests to verify endpoint compatibility

Files Modified

• Created: API_ENDPOINT_AUDIT.md - This audit report

Next Steps

1. Fix frontend paths that don't match backend
2. Remove or implement missing endpoints
3. Add integration tests for endpoint verification
4. Create automated endpoint validation in CI/CD