MediaCollectorLibaryFrontend/API_INTEGRATION.md

API Integration Guide

This document explains how the React frontend integrates with the PHP backend API.

API Configuration

Environment Setup

1. Copy .env.example to .env:

cp .env.example .env

2. Configure your API URL in .env:

VITE_API_URL=http://localhost:8080/api

Available API Endpoints

Based on your backend routes, the following endpoints are available:

Authentication

• POST /api/auth/login - User login
• POST /api/auth/register - User registration
• POST /api/auth/refresh - Refresh JWT token
• GET /api/auth/me - Get current user (protected)

Media

• GET /api/movies - List movies with pagination
• GET /api/movies/{id} - Get single movie
• GET /api/tvshows - List TV shows with pagination
• GET /api/tvshows/{id} - Get single TV show
• GET /api/games - List games with pagination
• GET /api/games/{id} - Get single game

Search

• GET /api/search?q={query}&type={type} - Search across media types

System

• GET /api/status - API health check

API Service Structure

The frontend is organized with:

1. API Service (src/services/api.ts)

   • Axios configuration with interceptors
   • Authentication handling
   • Endpoint methods

2. React Hooks (src/hooks/useApi.ts)

   • React Query integration
   • Custom hooks for each endpoint
   • Caching and error handling

3. Updated Components

   • Movies page now uses useMovies() hook
   • Dashboard uses useDashboardStats() and useRecentActivity()
   • Search page uses useSearch() hook

Authentication Flow

1. Login via /api/auth/login
2. Store JWT token in localStorage
3. Token automatically added to all requests
4. Auto-logout on 401 responses

Pagination

All list endpoints support:

• page - Page number (default: 1)
• per_page - Items per page (default: 20)
• search - Search term
• genre - Filter by genre
• year - Filter by year

Error Handling

• 401: Auto-redirect to login
• 404: Show "not found" message
• 500: Show generic error message
• Network: Show connection error

Next Steps

1. Complete Backend Endpoints: Your MediaController needs implementations for:

   • listMovies() method
   • getMovie() method
   • Dashboard stats endpoint
   • Recent activity endpoint

2. Add Missing Features:

   • Music API endpoints
   • Adult content API endpoints
   • Actors/performers API endpoints
   • CRUD operations (create, update, delete)

3. Testing:

   • Test API connectivity
   • Test authentication flow
   • Test error handling

Example API Response Format

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "total": 100,
      "per_page": 20,
      "current_page": 1,
      "last_page": 5
    }
  }
}

Development Notes

• The frontend includes fallback mock data
• API calls are made through React Query for caching
• All requests include JWT authentication headers
• CORS is configured for development