biblequizappapi-a6y6rm/README.md

Bible Quiz App API

A FastAPI-based REST API for a Bible Quiz application with user management, questions, and quiz features.

Features

• User Management: Registration, authentication, and profile management
• Questions Management: Create and manage Bible-related questions with multiple-choice options
• Quiz Management: Create quizzes from questions with customizable settings
• Quiz Taking: Take quizzes and receive scores
• Bible Data: Pre-loaded with Bible books and categorization

Tech Stack

• Framework: FastAPI (Python)
• Database: SQLite
• ORM: SQLAlchemy
• Migrations: Alembic
• Authentication: JWT (JSON Web Tokens)
• Password Hashing: Bcrypt

API Documentation

The API documentation is available at:

• Swagger UI: /docs
• ReDoc: /redoc
• OpenAPI JSON: /openapi.json

Setup and Installation

Prerequisites

• Python 3.8+
• pip (Python package manager)

Installation

1. Clone the repository:

git clone <repository-url>
cd biblequizappapi

2. Create and activate a virtual environment (optional but recommended):

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Setup environment variables (create a .env file in the root directory):

SECRET_KEY=your_secret_key_here
ACCESS_TOKEN_EXPIRE_MINUTES=60

Database Setup

1. Initialize the database and run migrations:

alembic upgrade head

Running the API

1. Start the server:

uvicorn main:app --reload

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

Environment Variables

Variable	Description	Default Value
SECRET_KEY	Secret key for JWT token generation	"change_this_secret_key_in_production"
ACCESS_TOKEN_EXPIRE_MINUTES	JWT token expiration time in minutes	60

API Endpoints

Health Check

• GET /health - Check API health

Authentication

• POST /api/v1/auth/register - Register a new user
• POST /api/v1/auth/login - Login with username and password (OAuth2 form)
• POST /api/v1/auth/login/json - Login with username and password (JSON)
• GET /api/v1/auth/me - Get current user information

Users

• GET /api/v1/users/ - List users (admin only)
• POST /api/v1/users/ - Create user (admin only)
• GET /api/v1/users/{user_id} - Get user details
• PUT /api/v1/users/{user_id} - Update user

Questions

• GET /api/v1/questions/ - List questions (with filtering options)
• POST /api/v1/questions/ - Create question (admin only)
• GET /api/v1/questions/{question_id} - Get question details
• PUT /api/v1/questions/{question_id} - Update question (admin only)
• DELETE /api/v1/questions/{question_id} - Delete question (admin only)
• GET /api/v1/questions/categories/ - List question categories
• GET /api/v1/questions/difficulties/ - List question difficulties
• GET /api/v1/questions/bible-books/ - List Bible books

Quizzes

• GET /api/v1/quizzes/ - List quizzes (public and user's own)
• POST /api/v1/quizzes/ - Create quiz
• GET /api/v1/quizzes/{quiz_id} - Get quiz details
• PUT /api/v1/quizzes/{quiz_id} - Update quiz
• DELETE /api/v1/quizzes/{quiz_id} - Delete quiz
• GET /api/v1/quizzes/attempts/ - List user's quiz attempts
• POST /api/v1/quizzes/{quiz_id}/start - Start a new quiz attempt
• GET /api/v1/quizzes/attempts/{attempt_id} - Get quiz attempt details
• POST /api/v1/quizzes/attempts/{attempt_id}/submit/{question_id} - Submit answer for a quiz question
• POST /api/v1/quizzes/attempts/{attempt_id}/complete - Complete quiz and get score

Development

Code Structure

.
├── alembic.ini              # Alembic configuration file
├── app/                     # Application package
│   ├── api/                 # API endpoints
│   │   ├── deps.py          # Dependencies (auth, etc.)
│   │   └── v1/              # API version 1
│   │       ├── api.py       # API router
│   │       └── endpoints/   # Endpoint modules
│   ├── core/                # Core functionality
│   │   ├── config.py        # Configuration settings
│   │   └── security.py      # Security utilities
│   ├── db/                  # Database
│   │   └── session.py       # DB session management
│   ├── models/              # SQLAlchemy models
│   ├── schemas/             # Pydantic schemas
│   └── services/            # Business logic
├── migrations/              # Alembic migrations
├── main.py                  # Application entry point
└── requirements.txt         # Project dependencies

Running Tests

pytest

License

MIT License