1754fec627
- Set up project structure with FastAPI and SQLite - Create models for users, questions, and quizzes - Implement Alembic migrations with seed data - Add user authentication with JWT - Implement question management endpoints - Implement quiz creation and management - Add quiz-taking and scoring functionality - Set up API documentation and health check endpoint - Update README with comprehensive documentation
169 lines
4.9 KiB
Markdown
169 lines
4.9 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
git clone <repository-url>
|
|
cd biblequizappapi
|
|
```
|
|
|
|
2. Create and activate a virtual environment (optional but recommended):
|
|
|
|
```bash
|
|
python -m venv venv
|
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
```
|
|
|
|
3. Install dependencies:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
alembic upgrade head
|
|
```
|
|
|
|
### Running the API
|
|
|
|
1. Start the server:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
pytest
|
|
```
|
|
|
|
## License
|
|
|
|
[MIT License](LICENSE) |