Random Word API

A lightweight, Dockerized REST API built with FastAPI that serves random words. Ideal for games like Hangman, Pictionary, or typing practice apps.

🌐 Live Demo

You can test the API live at: https://random.out.jafre.li/random_word

🚀 Features

• Random Word Generation: Efficiently retrieves a random word from a SQLite database.
• Fast & Lightweight: Built on Python 3.12 and FastAPI.
• Docker Ready: Includes a production-ready Dockerfile with uv for fast builds.
• Persistent Storage: Configurable database path for data persistence.

🛠️ Tech Stack

• Framework: FastAPI
• Database: SQLite
• Server: Uvicorn / Gunicorn
• Package Manager: uv
• Containerization: Docker

🔌 API Endpoints

GET /random_word

Returns a single random word from the database.

Response:

{
  "word": "Schmetterling"
}

Error Response:

{
  "error": "Keine Wörter in hangman.db gefunden."
}

🏁 Getting Started

Local Development

1. Clone the repository:

   git clone https://git.out.jafre.li/jafreli/Random-Word-API.git
   cd Random-Word-API
   

2. Install dependencies: If you use uv you can scip this step. This project uses uv for package management, but standard pip works too.

   pip install -r pyproject.toml
   # OR if you have uv installed:
   uv pip install -r pyproject.toml
   

3. Initialize the database: Run the initialization script to create hangman.db and populate it with the default word list.

   python init.py
   # OR
   uv run init.py
   

4. Start the server:

   uv run uvicorn main:app --reload
   

   The API will be available at http://localhost:8000/random_word.

🐳 Docker Usage

1. Build the image:

   docker build -t random-word-api .
   

2. Run the container: Mount a volume to /app/data to persist the database.

   docker run -d -p 8080:80 -v $(pwd)/data:/app/data random-word-api
   

   Note: The container is configured to look for the database at /app/data/hangman.db by default.

3. Access the API: Go to http://localhost:8080/random_word.

⚙️ Configuration

You can configure the application using environment variables:

Variable	Description	Default
DB_PATH	Path to the SQLite database file.	hangman.db (Local) / /app/data/hangman.db (Docker)