Library Backend API

A comprehensive FastAPI-based backend service for managing and organizing your personal media library. This API allows users to search, discover, and manage movies, TV series, anime, games, books, and manga from multiple external data sources.

Features

• User Authentication: Secure JWT-based authentication with refresh tokens
• Multi-Media Support: Integrate movies, TV series, anime, games, books, and manga
• Advanced Search: Search media from multiple external APIs (TMDB, OMDB, MyAnimeList, RAWG, Open Library, Jikan)
• Personal Library: Create and manage your personal collection of media
• Email Verification: Verify user emails with secure verification links
• Rate Limiting: Built-in rate limiting to prevent abuse
• Role-Based Access: Admin and user roles for different access levels
• Session Management: Redis-based session management
• Automatic Updates: Check for new episodes, chapters, and releases
• CORS Support: Configured for cross-origin requests
• API Documentation: Auto-generated interactive API docs with Swagger UI

Tech Stack

Backend Framework

• FastAPI: Modern, fast web framework for building APIs
• Python 3.10+: Core programming language

Database

• PostgreSQL: Primary relational database
• SQLAlchemy: ORM for database operations
• Alembic: Database migration tool

Authentication & Security

• JWT (JSON Web Tokens): Secure token-based authentication
• PyJWT: JWT token management
• python-jose: JWT and cryptography operations
• passlib: Password hashing and verification

External Integrations

• HTTPX: Async HTTP client for external API calls
• TMDB API: Movie and series data
• MyAnimeList API: Anime data
• RAWG API: Video games data
• Open Library API: Books data
• Jikan API: Manga and anime data
• Brevo (Sendinblue): Email delivery service

Utilities

• Redis: Caching and session management
• python-dotenv: Environment variable management
• SlowAPI: Rate limiting middleware
• Pydantic: Data validation and settings management

Project Structure

library_backend/
├── app/                          # Main application package
│   ├── config.py                 # Configuration and settings
│   ├── redis_client.py           # Redis client setup
│   ├── core/                     # Core utilities
│   │   ├── logging.py            # Logging configuration
│   │   └── rate_limit.py         # Rate limiting setup
│   ├── db/                       # Database layer
│   │   ├── database_setup.py     # Database connection
│   │   ├── models/               # SQLAlchemy models
│   │   │   ├── users_model.py
│   │   │   ├── email_verification_model.py
│   │   │   ├── refresh_token_model.py
│   │   │   ├── media_model.py
│   │   │   └── user_media_model.py
│   │   └── schemas/              # Pydantic schemas
│   │       ├── users_schema.py
│   │       ├── access_token_schema.py
│   │       ├── media_schema.py
│   │       └── user_media_schema.py
│   ├── fechers/                  # External API integrations
│   │   ├── httpx_client.py       # HTTP client configuration
│   │   ├── utils.py              # Fetcher utilities
│   │   ├── apis/                 # API fetchers
│   │   │   ├── movies_fetcher.py
│   │   │   ├── series_fetcher.py
│   │   │   ├── anime_fetcher.py
│   │   │   ├── games_fetcher.py
│   │   │   ├── books_fetcher.py
│   │   │   └── manga_fetcher.py
│   │   └── websites/             # Custom website scrapers
│   ├── routers/                  # API route handlers
│   │   ├── auth.py               # Authentication routes
│   │   ├── users.py              # User management routes
│   │   ├── fetcher.py            # Media search routes
│   │   ├── movies.py
│   │   ├── series.py
│   │   ├── anime.py
│   │   ├── games.py
│   │   ├── books.py
│   │   ├── manga.py
│   │   └── user_media.py         # Personal library routes
│   ├── security/                 # Security modules
│   │   └── oauth2.py             # OAuth2 and JWT implementation
│   ├── services/                 # Business logic services
│   └── utils/                    # Utility functions
│       ├── email.py              # Email utilities
│       └── password_hash.py      # Password hashing utilities
├── alembic/                      # Database migrations
│   ├── env.py
│   ├── script.py.mako
│   └── versions/
├── tests/                        # Test suite
│   └── locustfile.py             # Load testing configuration
├── main.py                       # Application entry point
├── requirements.txt              # Python dependencies
├── alembic.ini                   # Alembic configuration
├── .env.example                  # Environment variables template
└── README.md                     # This file

Prerequisites

• Python 3.10 or higher
• PostgreSQL 12 or higher
• Redis 6 or higher
• Git

Installation

1. Clone the Repository

git clone <repository-url>
cd library_backend

2. Create Virtual Environment

# Using venv
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

Configuration

1. Environment Variables

Create a .env file in the project root with the following variables:

# Database Configuration
DATABASE_HOSTNAME=localhost
DATABASE_PORT=5432
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=your_password
DATABASE_NAME=library_db

# JWT Configuration
SECRET_KEY=your-secret-key-here-change-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7

# External APIs
TMDB_API_KEY=your_tmdb_api_key
OMDB_API_KEY=your_omdb_api_key
MY_ANIME_LIST=your_mal_api_key
RAWG_API_KEY=your_rawg_api_key

# Email Configuration
BREVO_API_KEY=your_brevo_api_key
MAIL_FROM=noreply@yourdomain.com

# Redis Configuration
REDIS_URL=redis://localhost:6379

# Application Mode
DEBUG=true

2. Database Setup

# Run Alembic migrations
alembic upgrade head

# Or create tables directly
python -c "from app.db.database_setup import Base, engine; Base.metadata.create_all(bind=engine)"

Running the Application

Development Mode

# Using Uvicorn directly
uvicorn main:app --reload

# Or with custom host/port
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Production Mode

Set DEBUG=false in .env and run:

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

Using Procfile (Heroku)

heroku local

API Documentation

Once the application is running, access the interactive API documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json

(Only available in DEBUG mode)

API Endpoints

Authentication Routes (/auth)

• POST /auth/login - User login
• POST /auth/register - User registration
• POST /auth/refresh - Refresh access token
• POST /auth/logout - User logout

Users Routes (/users)

• GET /users/me - Get current user profile
• PUT /users/{user_id} - Update user profile
• DELETE /users/{user_id} - Delete user account
• POST /users/register - Register new user

Media Search Routes (/search)

• GET /search/movies/tmdb - Search movies from TMDB
• GET /search/series/tmdb - Search TV series from TMDB
• GET /search/anime/mal - Search anime from MyAnimeList
• GET /search/games/rawg - Search games from RAWG
• GET /search/books/ol - Search books from Open Library
• GET /search/manga/jikan - Search manga from Jikan

Personal Library Routes (/user-media)

• GET /user-media - Get user's media library
• POST /user-media - Add media to library
• PUT /user-media/{id} - Update media in library
• DELETE /user-media/{id} - Remove media from library
• GET /user-media/{id} - Get specific media details

Media Routes

• GET /movies - Get movies in library
• GET /series - Get TV series in library
• GET /anime - Get anime in library
• GET /games - Get games in library
• GET /books - Get books in library
• GET /manga - Get manga in library

Database Models

Users

• id, email, hashed_password, is_verified, is_admin, created_at, updated_at

EmailVerification

• id, user_id, token, created_at, expires_at

RefreshToken

• id, user_id, token, created_at, expires_at

Media

• id, title, description, media_type, external_api_id, created_at, updated_at

UserMedia

• id, user_id, media_id, status (watching/completed/dropped), rating, created_at, updated_at

Rate Limiting

The API implements rate limiting for security:

• Login endpoint: 10 requests per minute
• Register endpoint: 5 requests per minute
• General endpoints: 100 requests per minute (default)

Running Tests

Load Testing with Locust

locust -f tests/locustfile.py --host=http://localhost:8000

Access Locust UI at http://localhost:8089

Development

Code Structure Best Practices

• Place business logic in services/ directory
• Keep database queries in db/ directory
• Use schemas for request/response validation
• Follow FastAPI conventions for router organization
• Use dependency injection for database sessions

Making Changes

1. Create a new branch for your feature
2. Make your changes
3. Write/update tests
4. Submit a pull request

Troubleshooting

Database Connection Issues

# Check PostgreSQL is running
# Verify .env DATABASE_* variables are correct
# Ensure database exists:
psql -U postgres -c "CREATE DATABASE library_db;"

Redis Connection Issues

# Check Redis is running
redis-cli ping
# Should return: PONG

External API Issues

• Verify API keys are valid in .env
• Check API rate limits haven't been exceeded
• Ensure internet connection is stable

Environment Variables Reference

Variable	Description	Required
DATABASE_HOSTNAME	PostgreSQL server hostname	Yes
DATABASE_PORT	PostgreSQL server port	Yes
DATABASE_USERNAME	PostgreSQL username	Yes
DATABASE_PASSWORD	PostgreSQL password	Yes
DATABASE_NAME	PostgreSQL database name	Yes
SECRET_KEY	JWT secret key	Yes
ALGORITHM	JWT algorithm (HS256)	Yes
ACCESS_TOKEN_EXPIRE_MINUTES	JWT token expiration in minutes	Yes
REFRESH_TOKEN_EXPIRE_DAYS	Refresh token expiration in days	Yes
TMDB_API_KEY	The Movie Database API key	Yes
OMDB_API_KEY	Open Movie Database API key	Yes
MY_ANIME_LIST	MyAnimeList API key	Yes
RAWG_API_KEY	RAWG Video Games API key	Yes
BREVO_API_KEY	Brevo email service API key	Yes
MAIL_FROM	Sender email address	Yes
REDIS_URL	Redis connection URL	No
DEBUG	Debug mode (true/false)	No

Security Considerations

• Never commit .env file to version control
• Use strong SECRET_KEY in production
• Enable HTTPS in production
• Implement CSRF protection if serving web clients
• Regularly update dependencies for security patches
• Use environment variables for sensitive data

Performance Tips

• Use Redis for caching frequently searched items
• Enable database query optimization
• Consider pagination for large result sets
• Use async/await for external API calls
• Monitor rate limiting to prevent abuse

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is free for personal use only