jafreli
ee06bb5274
All checks were successful
Build and Push Docker Image / build (push) Successful in 31s
101 lines
2.5 KiB
Markdown
101 lines
2.5 KiB
Markdown
# 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) |
|