veza/apps/web/docs/ENDPOINT_SCHEMA_AUDIT.md

Endpoint Request Schema Audit

Date: 2025-01-27
Action: 1.2.1.3 - Audit all API endpoints for request schemas
Status: ✅ Complete

Overview

This document provides a comprehensive audit of all API endpoints and their request schema coverage status.

Methodology

1. Extracted all endpoints from veza-backend-api/docs/swagger.json
2. Identified endpoints that require request bodies (POST, PUT, PATCH)
3. Cross-referenced with existing schemas in apps/web/src/schemas/apiRequestSchemas.ts
4. Categorized by schema status: ✅ Has Schema, ⚠️ Missing Schema, ➖ No Body Required

Summary Statistics

• Total Endpoints: 56 endpoints
• Endpoints Requiring Request Bodies: 25 endpoints
• Endpoints with Schemas: 9 endpoints (36%)
• Endpoints Missing Schemas: 16 endpoints (64%)
• GET/DELETE Endpoints (no body): 31 endpoints

Endpoints with Request Schemas ✅

Authentication (3/6)

• ✅ POST /auth/login - loginRequestSchema
• ✅ POST /auth/register - registerRequestSchema
• ✅ POST /auth/refresh - refreshRequestSchema
• ⚠️ POST /auth/2fa/setup - Missing schema
• ⚠️ POST /auth/2fa/verify - Missing schema
• ⚠️ POST /auth/2fa/disable - Missing schema

Tracks (2/6)

• ✅ POST /tracks - createTrackRequestSchema / uploadTrackRequestSchema
• ✅ PUT /tracks/{id} - updateTrackRequestSchema
• ⚠️ POST /tracks/batch/delete - Missing schema (BatchDeleteRequest)
• ⚠️ POST /tracks/initiate - Missing schema (InitiateChunkedUploadRequest)
• ⚠️ POST /tracks/chunk - Missing schema (UploadChunkRequest)
• ⚠️ POST /tracks/complete - Missing schema (CompleteChunkedUploadRequest)

Playlists (2/3)

• ✅ POST /playlists - createPlaylistRequestSchema
• ✅ POST /playlists/{id}/tracks - addTrackToPlaylistRequestSchema
• ⚠️ PUT /playlists/{id} - Missing schema (updatePlaylistRequestSchema exists but not verified)

Comments (2/2)

• ✅ POST /tracks/{id}/comments - createCommentRequestSchema
• ✅ PUT /comments/{id} - updateCommentRequestSchema (via PUT /tracks/{id}/comments/{comment_id})

Users (2/2)

• ✅ POST /users - createUserRequestSchema
• ✅ PUT /users/{id} - updateUserRequestSchema

Endpoints Missing Request Schemas ⚠️

Analytics (1)

• ⚠️ POST /analytics/events - RecordEventRequest
  • Fields: event_type, properties, user_id, timestamp
  • Priority: MEDIUM

Marketplace (2)

• ⚠️ POST /api/v1/marketplace/products - CreateProductRequest

  • Fields: name, description, price, type, file_url
  • Priority: LOW (feature may not be active)

• ⚠️ POST /api/v1/marketplace/orders - CreateOrderRequest

  • Fields: product_id, quantity, payment_method
  • Priority: LOW (feature may not be active)

Webhooks (1)

• ⚠️ POST /webhooks - CreateWebhookRequest
  • Fields: url, events[], secret
  • Priority: MEDIUM

Two-Factor Authentication (3)

• ⚠️ POST /auth/2fa/setup - Setup2FARequest

  • Fields: password (for verification)
  • Priority: HIGH (security feature)

• ⚠️ POST /auth/2fa/verify - Verify2FARequest

  • Fields: code (TOTP code)
  • Priority: HIGH (security feature)

• ⚠️ POST /auth/2fa/disable - Disable2FARequest

  • Fields: password, code
  • Priority: HIGH (security feature)

Upload Chunking (3)

• ⚠️ POST /tracks/initiate - InitiateChunkedUploadRequest

  • Fields: filename, total_chunks, total_size
  • Priority: MEDIUM

• ⚠️ POST /tracks/chunk - UploadChunkRequest

  • Fields: upload_id, chunk_number, chunk_data
  • Priority: MEDIUM

• ⚠️ POST /tracks/complete - CompleteChunkedUploadRequest

  • Fields: upload_id
  • Priority: MEDIUM

Batch Operations (1)

• ⚠️ POST /tracks/batch/delete - BatchDeleteRequest
  • Fields: track_ids[]
  • Priority: MEDIUM

Frontend Logging (1)

• ⚠️ POST /api/v1/logs/frontend - FrontendLogRequest
  • Fields: level, message, context, timestamp
  • Priority: LOW

Other (1)

• ⚠️ POST /auth/resend-verification - ResendVerificationRequest
  • Fields: email
  • Priority: LOW

Endpoints Not Requiring Request Bodies ➖

GET Endpoints (28)

• GET /analytics
• GET /analytics/tracks/{id}
• GET /analytics/tracks/top
• GET /audit/activity
• GET /audit/logs
• GET /audit/stats
• GET /auth/2fa/status
• GET /auth/check-username
• GET /auth/me
• GET /chat/token
• GET /comments/{id}/replies
• GET /playlists
• GET /playlists/{id}
• GET /tracks
• GET /tracks/{id}
• GET /tracks/{id}/analytics/plays
• GET /tracks/{id}/comments
• GET /tracks/{id}/stats
• GET /tracks/{id}/status
• GET /tracks/quota/{id}
• GET /tracks/resume/{uploadId}
• GET /users
• GET /users/by-username/{username}
• GET /users/{id}
• GET /users/{id}/analytics/stats
• GET /users/{id}/completion
• GET /webhooks
• GET /webhooks/stats

Note: GET endpoints may have query parameters that should be validated, but they don't require request body schemas.

DELETE Endpoints (3)

• DELETE /playlists/{id}
• DELETE /playlists/{id}/tracks/{trackId}
• DELETE /tracks/{id}
• DELETE /tracks/{id}/comments/{comment_id}
• DELETE /users/{id}
• DELETE /webhooks/{id}

Note: DELETE endpoints typically don't require request bodies.

Priority Ranking for Missing Schemas

HIGH Priority (Security Features)

1. POST /auth/2fa/setup - Two-factor setup
2. POST /auth/2fa/verify - Two-factor verification
3. POST /auth/2fa/disable - Two-factor disable

MEDIUM Priority (Core Features)

4. POST /tracks/batch/delete - Batch operations
5. POST /tracks/initiate - Chunked upload initiation
6. POST /tracks/chunk - Chunk upload
7. POST /tracks/complete - Chunked upload completion
8. POST /analytics/events - Analytics tracking
9. POST /webhooks - Webhook creation

LOW Priority (Optional/Edge Cases)

10. POST /api/v1/marketplace/products - Marketplace (may not be active)
11. POST /api/v1/marketplace/orders - Marketplace (may not be active)
12. POST /api/v1/logs/frontend - Frontend logging
13. POST /auth/resend-verification - Email verification

Next Steps

• ✅ Action 1.2.1.3: Audit complete - This document
• ⏭️ Action 1.2.1.4: Add request validation schemas for missing endpoints
  • Start with HIGH priority (2FA schemas)
  • Then MEDIUM priority (upload chunking, batch operations)
  • Finally LOW priority (marketplace, logging)

Validation

✅ All endpoints extracted from Swagger spec
✅ Request body endpoints identified
✅ Existing schemas mapped
✅ Missing schemas categorized by priority
✅ 16 missing schemas identified (64% coverage gap)