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)