fastapi-inventory/README.md

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:

   git clone <repository-url>
   cd fastapi-inventory
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure Discogs API (Required for music searches):

   • Go to Discogs Developer Settings
   • Create a new application or use an existing one
   • Generate a User Token
   • Copy the example environment file and add your token:

   # 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:

   python main.py
   

   Or using uvicorn directly:

   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:

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.