API Documentation

Overview

This Express TypeScript project implements a RESTful API to crop and download youtube videos based on specified time

Video Processing API

The API is built with modern TypeScript practices and includes OpenAPI (Swagger) documentation integration using @asteasolutions/zod-to-openapi for automatic API documentation generation.

API Endpoints

1. Health Check API

Endpoint: GET /health-check Purpose: Provides system health monitoring capabilities

• Returns a status check of the service
• Used for monitoring and ensuring the service is running properly
• Returns a standardized ServiceResponse with a "Service is healthy" message

2. Youtube Video Processing API

Endpoint: POST /videos/process Purpose: Processes YouTube videos with specific time segments

Features:

• Downloads YouTube videos using youtube-dl-exec
• Processes videos using ffmpeg with the following capabilities:
  • Time segment extraction (using start and end times)
  • High-quality video processing with H.264 codec
  • Audio processing with AAC codec at 192k bitrate
  • Maintains original video resolution
  • Optimized compression using slow preset for better quality

Request Format:

{
  youtubeUrl: string,    // URL of the YouTube video --- (https://www.youtube.com/watch?v=GimCcrwYxdE)
  startTime: string,     // Start time in "MM:SS" format (e.g., "2:56")
  endTime: string        // End time in "MM:SS" format
}

Response Format:

{
  id: string,            // Unique UUID for the processed video
  originalUrl: string,   // Original YouTube URL
  processedUrl: string,  // URL of the processed video
  startTime: string,     // Requested start time
  endTime: string,       // Requested end time
  createdAt: Date       // Processing timestamp
}

Architecture

The API follows a clean architecture pattern with the following components:

1. Routers (*Router.ts)

• Handle HTTP route definitions
• Integrate OpenAPI documentation
• Define request/response schemas using Zod
• Map routes to controllers

2. Controllers (videoController.ts)

• Handle HTTP request/response logic
• Validate incoming requests
• Delegate business logic to services

3. Services (videoService.ts)

• Implement core business logic
• Handle video processing operations
• Manage error handling and response formatting

4. Models (videoModel.ts)

• Define data structures and types
• Implement validation schemas using Zod
• Ensure type safety throughout the application

5. Repositories (videoRepository.ts)

• Handle data persistence
• Manage file uploads and storage
• Interface with external storage services

Error Handling

The API implements robust error handling with:

• Standardized ServiceResponse format for all responses
• HTTP status code mapping
• Detailed error messages for debugging
• Logging integration for error tracking

Security Features

• Rate limiting middleware
• Request logging for audit trails
• Input validation using Zod schemas
• Secure file handling with temporary storage cleanup

Documentation Features

• OpenAPI (Swagger) integration
• Automatic API documentation generation
• Type-safe request/response schemas
• Clear endpoint descriptions and tags

Technical Stack

• Express.js with TypeScript
• Zod for validation
• FFmpeg for video processing
• youtube-dl for video downloading
• OpenAPI for API documentation
• Custom middleware for logging and error handling

This API is designed to be scalable, maintainable, and follows best practices for TypeScript/Express applications with a focus on type safety and proper error handling.

Developer HINT

If you want to implement a more secure approach when connecting to your local server, you can implement and extend the current functionality to accept an Authorization header, include your API key, and implement API key validation in a suitable middleware.