grabowski
877ef951b2
- Added comprehensive .gitignore to prevent sensitive data commits - Removed .env from git tracking to protect API tokens - Created .env.example template for users to copy and configure - Updated README with secure setup instructions using .env.example - Prevents accidental exposure of Discogs API tokens and other secrets
145 lines
4.4 KiB
Markdown
145 lines
4.4 KiB
Markdown
# Media Inventory App
|
|
|
|
A FastAPI-based web application that allows users to search for different types of media (books, vinyl records, CDs, and cassettes) using external APIs.
|
|
|
|
## Features
|
|
|
|
- 📚 **Book Search**: Search for books using the OpenLibrary API
|
|
- 🎵 **Music Search**: Search for vinyl records, CDs, and cassettes using the Discogs API
|
|
- 🎨 **Clean UI**: Bootstrap-based responsive web interface
|
|
- 🔍 **Smart Search**: Different search parameters based on media type
|
|
- 📱 **Mobile Friendly**: Responsive design that works on all devices
|
|
|
|
## APIs Used
|
|
|
|
- **OpenLibrary**: For book information and covers
|
|
- **Discogs**: For music releases and album art
|
|
|
|
## Installation
|
|
|
|
1. **Clone the repository**:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd fastapi-inventory
|
|
```
|
|
|
|
2. **Install dependencies**:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
3. **Configure Discogs API (Required for music searches)**:
|
|
- Go to [Discogs Developer Settings](https://www.discogs.com/settings/developers)
|
|
- Create a new application or use an existing one
|
|
- Generate a User Token
|
|
- Copy the example environment file and add your token:
|
|
```bash
|
|
# Copy the example file
|
|
cp .env.example .env
|
|
|
|
# Edit .env file and add your actual token
|
|
DISCOGS_USER_TOKEN=your_actual_discogs_token_here
|
|
DISCOGS_USER_AGENT=YourAppName/1.0 +http://yourwebsite.com
|
|
```
|
|
|
|
4. **Run the application**:
|
|
```bash
|
|
python main.py
|
|
```
|
|
|
|
Or using uvicorn directly:
|
|
```bash
|
|
uvicorn main:app --reload --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
5. **Open your browser** and navigate to:
|
|
```
|
|
http://localhost:8000
|
|
```
|
|
|
|
## Usage
|
|
|
|
1. **Select Media Type**: Choose from Book, Vinyl Record, CD, or Cassette
|
|
2. **Enter Search Query**: Type the title, album name, or keywords
|
|
3. **Add Artist (Optional)**: For music searches, you can specify an artist to narrow results
|
|
4. **Search**: Click the search button to get results
|
|
5. **View Details**: Click on the external links to view more information on the source websites
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
fastapi-inventory/
|
|
├── main.py # FastAPI application
|
|
├── requirements.txt # Python dependencies
|
|
├── README.md # This file
|
|
├── templates/ # Jinja2 HTML templates
|
|
│ ├── base.html # Base template
|
|
│ ├── index.html # Search form
|
|
│ └── results.html # Search results
|
|
└── static/ # Static files
|
|
└── style.css # Custom CSS styles
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
- `GET /`: Main search form
|
|
- `POST /search`: Process search requests and return results
|
|
- `GET /docs`: FastAPI automatic API documentation
|
|
- `GET /redoc`: Alternative API documentation
|
|
|
|
## Dependencies
|
|
|
|
- **FastAPI**: Modern, fast web framework for building APIs
|
|
- **Uvicorn**: ASGI server for running FastAPI
|
|
- **httpx**: Async HTTP client for API requests
|
|
- **Jinja2**: Template engine for HTML rendering
|
|
- **python-multipart**: For handling form data
|
|
|
|
## External APIs
|
|
|
|
### OpenLibrary API
|
|
- **Endpoint**: `https://openlibrary.org/search.json`
|
|
- **Usage**: Search for books by title, author, or keywords
|
|
- **Rate Limits**: No authentication required, reasonable rate limits
|
|
|
|
### Discogs API
|
|
- **Endpoint**: `https://api.discogs.com/database/search`
|
|
- **Usage**: Search for music releases by title, artist, or format
|
|
- **Rate Limits**: No authentication required for basic searches, 60 requests per minute
|
|
|
|
## Features in Detail
|
|
|
|
### Book Search
|
|
- Searches OpenLibrary for book information
|
|
- Displays title, author, publication year, and ISBN
|
|
- Shows book covers when available
|
|
- Links to OpenLibrary pages for more details
|
|
|
|
### Music Search
|
|
- Searches Discogs for music releases
|
|
- Supports vinyl, CD, and cassette formats
|
|
- Displays title, artist, year, label, and format information
|
|
- Shows album artwork when available
|
|
- Links to Discogs pages for more details
|
|
|
|
### User Interface
|
|
- Clean, modern design using Bootstrap 5
|
|
- Responsive layout that works on desktop and mobile
|
|
- Dynamic form that shows/hides artist field based on media type
|
|
- Card-based results display with consistent layout
|
|
- Error handling and user feedback
|
|
|
|
## Development
|
|
|
|
To run in development mode with auto-reload:
|
|
|
|
```bash
|
|
uvicorn main:app --reload --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
The application will automatically reload when you make changes to the code.
|
|
|
|
## License
|
|
|
|
This project is open source and available under the MIT License.
|