A Flask-based RESTful API for managing movie information, integrating with TheMovieDB. Built with hexagonal architecture, this API allows users to browse popular movies, maintain favorites lists, and rate movies.

• Browse popular movies from TheMovieDB
• Rate movies (0-5 stars)
• Manage favorite movies list
• Token-based authentication
• Redis caching
• Resilient external API calls
• Comprehensive test coverage

• Framework: Flask
• Database: PostgreSQL with SQLAlchemy ORM
• Cache: Redis
• External API: TheMovieDB
• Testing: pytest
• CI/CD: GitHub Actions
• Documentation: OpenAPI/Swagger
• Containerization: Docker & Docker Compose

• Python 3.8+
• Docker and Docker Compose
• TheMovieDB API Key

1. Clone the repository:

git clone https://github.com/sanjmen/flask-api.git
cd flask-api

2. Copy the example environment file:

cp .env.example .env

3. Update the .env file with your configuration:

# Flask configuration
FLASK_APP=app.main:app
FLASK_ENV=development
FLASK_DEBUG=1

# Database
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=movies
DATABASE_URL=postgresql://postgres:password@db:5432/movies_db

# Redis
REDIS_URL=redis://redis:6379/0
CACHE_DURATION_SECONDS=30

# TheMovieDB
TMDB_API_KEY=your_api_key_here

4. Start the services with Docker Compose:

docker compose up --build

The API will be available at http://localhost:5000/api

1. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # Linux/macOS

2. Install dependencies:

pip install -r requirements.txt

3. Install pre-commit hooks:

pre-commit install

4. Run the tests:

pytest

flask-api/
├── app/
│   ├── application/        # Application layer (controllers, DTOs)
│   ├── domain/            # Domain layer (entities, repositories interfaces)
│   └── infrastructure/    # Infrastructure layer (implementations)
├── tests/
│   ├── unit/             # Unit tests
│   └── integration/      # Integration tests
├── docker/               # Docker configuration files
├── .github/              # GitHub Actions workflows
├── API.md               # API documentation
├── docker-compose.yml
└── requirements.txt

• Project Structure
  • Hexagonal architecture setup
  • Application layers (application, domain, infrastructure)
  • Directory organization
  • Basic Flask application structure
• Development Environment
  • Docker configuration
  • Docker Compose setup
  • Environment variables configuration
  • Pre-commit hooks
• Database Setup
  • PostgreSQL configuration
  • SQLAlchemy integration
  • Basic database connection
• CI/CD Pipeline
  • GitHub Actions workflow
  • Basic test automation
  • Code quality checks
• Documentation
  • API documentation structure
  • README with setup instructions
  • Development roadmap
• Testing Foundation
  • pytest configuration
  • Basic test structure
  • First endpoint test

• HTTP client implementation
• Adapter in hexagonal architecture
• Error handling and retries
• Integration tests

• GET /api/movies/popular
• GET /api/movies/{id}
• Favorites Management
  • GET /api/users/{user_id}/favorites
  • POST /api/users/{user_id}/favorites
  • DELETE /api/users/{user_id}/favorites/{id}
  • Database models and repositories
  • Admin endpoint for user favorites
  • DELETE /api/admin/users/{userId}/favorites
• Movie Ratings
  • Database models and repositories
  • POST /api/movies/ratings
  • PUT /api/movies/ratings/{id}

• Redis configuration
• Cache middleware for GET endpoints
• Fallback mechanisms
• Cache tests

• Bearer token authentication
• Role-based access control
• Security tests

• Performance optimizations
• Complete CI/CD pipeline
• Production configuration
• OpenAPI specification
• Final documentation updates

Run unit tests:

pytest

Run integration tests:

pytest --integration

Note: Integration tests require a valid TMDB_API_KEY environment variable.

See API.md for detailed endpoint documentation.

Quick endpoint overview:

• GET /api/movies/popular - Get popular movies
• GET /api/movies/{id} - Get movie details
• GET /api/users/{user_id}/favorites - Get user's favorite movies
• POST /api/users/{user_id}/favorites - Add movie to favorites
• DELETE /api/users/{user_id}/favorites/{id} - Remove movie from favorites
• POST /api/movies/ratings - Rate a movie
• PUT /api/movies/ratings/{id} - Update movie rating

The API uses Bearer token authentication. Available tokens:

• Admin: abcdef1234567890
• User: 1234567890

Example:

curl -H "Authorization: Bearer abcdef1234567890" http://localhost:5000/api/movies/favorites

• GET endpoints are cached in Redis for 30 seconds (configurable)
• Cache duration can be modified via CACHE_DURATION_SECONDS environment variable
• Failed external API calls fall back to cached data

• All errors return a consistent JSON format
• External API calls implement retry with exponential backoff
• Detailed error logging to stderr
• See API.md for error codes and formats

GitHub Actions workflows:

• Run tests
• Code quality checks
• Security scanning
• Docker image building

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

This project is licensed under the MIT License - see the LICENSE file for details