9ed9654f1e
- Add advanced search filters (year range, score, studio, source) - Create detailed statistics endpoint for anime collection - Implement enhanced pagination metadata for better navigation - Add sorting options for search results - Enhance anime model with additional fields (season info, ratings, etc.) - Add ability to search anime by character attributes - Create migration for new anime model fields - Update README with detailed documentation of new features
202 lines
6.7 KiB
Markdown
202 lines
6.7 KiB
Markdown
# Anime Information API
|
|
|
|
This is a FastAPI application that provides anime information via a RESTful API.
|
|
|
|
## Features
|
|
|
|
- **Comprehensive Anime Information**: Extensive anime data including titles, synopsis, episodes, scores, studios, seasons, rating details, etc.
|
|
- **Genre Management**: Create, read, update, and delete anime genres
|
|
- **Character Management**: Create, read, update, and delete anime characters with detailed profiles
|
|
- **Advanced Search**: Search anime with multiple filters including year, score range, source, studio, etc.
|
|
- **Character-Based Anime Search**: Find anime based on character attributes like name, role, or gender
|
|
- **Smart Pagination**: Built-in pagination with rich metadata for easy navigation
|
|
- **Statistics Dashboard**: Get detailed statistical insights about the anime collection
|
|
- **Health Endpoint**: Check the health of the application and its database connection
|
|
|
|
## Tech Stack
|
|
|
|
- **Framework**: FastAPI
|
|
- **Database**: SQLite with SQLAlchemy ORM
|
|
- **Migration Tool**: Alembic
|
|
- **Validation**: Pydantic
|
|
- **Code Quality**: Ruff linter
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
anime-information-api/
|
|
├── alembic/ # Database migrations
|
|
├── app/ # Application code
|
|
│ ├── api/ # API endpoints
|
|
│ │ └── endpoints/ # Route definitions
|
|
│ ├── core/ # Core application components
|
|
│ ├── crud/ # CRUD operations
|
|
│ ├── db/ # Database setup
|
|
│ ├── initial_data/ # Data seeding
|
|
│ ├── models/ # SQLAlchemy models
|
|
│ └── schemas/ # Pydantic schemas
|
|
├── storage/ # Storage for SQLite database
|
|
├── alembic.ini # Alembic config
|
|
├── main.py # Application entry point
|
|
├── requirements.txt # Dependencies
|
|
└── seed_data.py # Script to seed initial data
|
|
```
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.9+
|
|
|
|
### Installation
|
|
|
|
1. Clone the repository
|
|
2. Install dependencies:
|
|
```
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### Database Setup
|
|
|
|
Run the Alembic migrations to set up the database schema:
|
|
|
|
```
|
|
alembic upgrade head
|
|
```
|
|
|
|
Seed the database with initial data:
|
|
|
|
```
|
|
python seed_data.py
|
|
```
|
|
|
|
### Running the Application
|
|
|
|
Start the application with:
|
|
|
|
```
|
|
uvicorn main:app --reload
|
|
```
|
|
|
|
The API will be available at http://localhost:8000, and the interactive API documentation at http://localhost:8000/docs.
|
|
|
|
## API Endpoints
|
|
|
|
### Health Check
|
|
- `GET /health`: Check application health
|
|
|
|
### Anime
|
|
- `GET /api/v1/anime/`: Get anime list with advanced filtering and pagination
|
|
- `GET /api/v1/anime/statistics`: Get statistics about the anime collection
|
|
- `GET /api/v1/anime/search-by-character`: Search anime by character attributes
|
|
- `POST /api/v1/anime/`: Create new anime
|
|
- `GET /api/v1/anime/{id}`: Get anime by ID
|
|
- `PUT /api/v1/anime/{id}`: Update anime
|
|
- `DELETE /api/v1/anime/{id}`: Delete anime
|
|
|
|
### Genres
|
|
- `GET /api/v1/genres/`: Get genre list
|
|
- `POST /api/v1/genres/`: Create new genre
|
|
- `GET /api/v1/genres/{id}`: Get genre by ID
|
|
- `PUT /api/v1/genres/{id}`: Update genre
|
|
- `DELETE /api/v1/genres/{id}`: Delete genre
|
|
|
|
### Characters
|
|
- `GET /api/v1/characters/`: Search characters with filters (name, anime_id, role)
|
|
- `POST /api/v1/characters/`: Create new character
|
|
- `GET /api/v1/characters/{id}`: Get character by ID
|
|
- `PUT /api/v1/characters/{id}`: Update character
|
|
- `DELETE /api/v1/characters/{id}`: Delete character
|
|
- `GET /api/v1/characters/anime/{anime_id}`: Get all characters for a specific anime
|
|
|
|
## Advanced Search Parameters
|
|
|
|
### Anime Search Parameters
|
|
|
|
The anime search endpoint supports the following parameters:
|
|
|
|
- `title`: Filter by title (partial match)
|
|
- `genre_id`: Filter by genre ID
|
|
- `status`: Filter by anime status (airing, finished, upcoming)
|
|
- `year_from`: Filter by starting year (inclusive)
|
|
- `year_to`: Filter by ending year (inclusive)
|
|
- `score_min`: Filter by minimum score (inclusive)
|
|
- `score_max`: Filter by maximum score (inclusive)
|
|
- `source`: Filter by source material (manga, light novel, etc.)
|
|
- `studio`: Filter by studio name (partial match)
|
|
- `sort_by`: Sort by field (id, title, score, popularity, etc.)
|
|
- `sort_order`: Sort order (asc, desc)
|
|
- `skip`: Number of items to skip for pagination
|
|
- `limit`: Maximum number of items to return
|
|
|
|
### Search by Character Parameters
|
|
|
|
The anime search-by-character endpoint supports the following parameters:
|
|
|
|
- `character_name`: Filter anime by character name (partial match)
|
|
- `character_role`: Filter anime by character role (e.g., "Main", "Supporting")
|
|
- `character_gender`: Filter anime by character gender
|
|
- `include_anime_filters`: Boolean flag to include anime filters below in the search
|
|
- Plus all the standard anime filters listed above (when include_anime_filters is set to true)
|
|
|
|
### Character Search Parameters
|
|
|
|
The character search endpoint supports the following parameters:
|
|
|
|
- `name`: Filter by character name (partial match)
|
|
- `anime_id`: Filter by anime ID
|
|
- `role`: Filter by character role (Main, Supporting, Antagonist, etc.)
|
|
- `skip`: Number of items to skip for pagination
|
|
- `limit`: Maximum number of items to return
|
|
|
|
## Anime Model
|
|
|
|
The anime model includes the following fields:
|
|
|
|
### Basic Information
|
|
- `title`: Main title of the anime
|
|
- `alternative_titles`: Other titles the anime is known by
|
|
- `synopsis`: Plot summary
|
|
- `episodes`: Number of episodes
|
|
- `status`: Airing status (airing, finished, upcoming)
|
|
- `aired_from`: Start date
|
|
- `aired_to`: End date
|
|
- `duration`: Episode duration
|
|
- `image_url`: URL to anime cover image
|
|
|
|
### Rating Information
|
|
- `rating`: Content rating (PG-13, R, etc.)
|
|
- `score`: Average user score (0-10)
|
|
- `score_count`: Number of users who rated
|
|
- `ranked`: Ranking position
|
|
- `popularity`: Popularity ranking
|
|
- `favorites_count`: Number of users who favorited
|
|
|
|
### Production Information
|
|
- `studio`: Animation studio
|
|
- `source`: Original source material
|
|
- `producers`: Production companies
|
|
- `licensors`: Companies with distribution licenses
|
|
|
|
### Season Information
|
|
- `season`: Broadcast season (Winter, Spring, Summer, Fall)
|
|
- `season_year`: Year of the season
|
|
- `broadcast_day`: Day of the week it airs
|
|
- `broadcast_time`: Time of day it airs
|
|
- `is_airing`: Whether it's currently airing
|
|
|
|
### Content Information
|
|
- `themes`: Major themes (School, Military, etc.)
|
|
- `demographics`: Target audience (Shounen, Seinen, etc.)
|
|
- `related_anime`: Related anime works (sequels, prequels, etc.)
|
|
|
|
## Statistics
|
|
|
|
The statistics endpoint provides the following information:
|
|
|
|
- Total anime count
|
|
- Average score and episode count
|
|
- Distribution by status, source, and studio
|
|
- Yearly distribution of releases
|
|
- Score distribution (0-1, 1-2, ... 9-10)
|
|
- Top genres with counts |