# Random Word API

A lightweight, Dockerized REST API built with [FastAPI](https://fastapi.tiangolo.com/) 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](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:**
```json
{
  "word": "Schmetterling"
}
```

**Error Response:**
```json
{
  "error": "Keine Wörter in hangman.db gefunden."
}
```

## 🏁 Getting Started

### Local Development

1.  **Clone the repository:**
    ```bash
    git clone https://git.out.jafre.li/jafreli/Random-Word-API.git
    cd Random-Word-API
    ```

2.  **Install dependencies:**
    This project uses `uv` for package management, but standard `pip` works too.
    ```bash
    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.
    ```bash
    python init.py
    ```

4.  **Start the server:**
    ```bash
    fastapi dev main.py
    # OR using uvicorn directly:
    uvicorn main:app --reload
    ```
    The API will be available at `http://localhost:8000/random_word`.

### 🐳 Docker Usage

1.  **Build the image:**
    ```bash
    docker build -t random-word-api .
    ```

2.  **Run the container:**
    Mount a volume to `/app/data` to persist the database.
    ```bash
    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) |