A REST API for an online book store designed as a layered monolithic application with a clear separation between API, business logic, data access, and persistence layers.
- Technology Stack
- Project Structure
- Quick Start
- API Documentation
- API Endpoints
- Request Examples
- Testing
- Environment Variables
- Database Migrations
- Notes
| Technology | Purpose |
|---|---|
| Python 3.14 | Application runtime |
| FastAPI | REST API framework |
| Pydantic v2 | Validation and serialization |
| SQLAlchemy 2.0 Async | ORM and asynchronous database access |
| PostgreSQL 16 | Relational database |
| Alembic | Database migrations |
| JWT | Access and refresh token authentication |
| Passlib / bcrypt | Password hashing and verification |
| Pytest | Automated testing |
| pytest-asyncio | Async test support |
| Ruff | Linter and code formatter |
| Docker | Containerized application runtime |
| Docker Compose | Local multi-container environment |
Book_Store_API/
├── alembic/
│ ├── versions/ # Database migration revisions
│ ├── env.py # Alembic configuration for async migrations
│ └── script.py.mako # Template used to generate new migration files
│
├── app/
│ ├── api/
│ │ ├── deps.py # Dependency providers
│ │ ├── router.py # Combines and registers API v1 routers
│ │ └── v1/
│ │ ├── auth.py # Authentication endpoints
│ │ ├── books.py # Book endpoints
│ │ ├── categories.py # Category endpoints
│ │ ├── orders.py # Order endpoints
│ │ └── users.py # User endpoints
│ │
│ ├── core/
│ │ ├── config.py # Application settings
│ │ ├── dependencies.py # Authentication / authorization dependencies
│ │ └── security.py # Password hashing and JWT helpers
│ │
│ ├── database/
│ │ ├── base.py # SQLAlchemy Base
│ │ ├── session.py # Async engine and session factory
│ │ └── init_db.py # Database initialization and default data setup
│ │
│ ├── exceptions/
│ │ ├── all_exceptions.py # Application exception definitions
│ │ └── exception_handlers # Global handlers for application exceptions
│ │
│ ├── models/
│ │ ├── __init__.py # Imports all models and makes them available to SQLAlchemy/Alembic
│ │ ├── user.py # User model
│ │ ├── book.py # Book model
│ │ ├── category.py # Category model
│ │ ├── book_category.py # Book/category association model
│ │ ├── order.py # Order model
│ │ ├── order_item.py # Order item model
│ │ ├── enums.py # User and order enums
│ │ └── mixins.py # Shared UUID/timestamp mixins
│ │
│ ├── repositories/
│ │ ├── base.py # Generic repository
│ │ ├── user.py # User data access
│ │ ├── book.py # Book data access
│ │ ├── category.py # Category data access
│ │ ├── order.py # Order data access
│ │ └── order_item.py # Order item data access
│ │
│ ├── schemas/
│ │ ├── user.py # User and token schemas
│ │ ├── book.py # Book schemas
│ │ ├── category.py # Category schemas
│ │ ├── order.py # Order schemas
│ │ └── order_item.py # Order item schemas
│ │
│ ├── services/
│ │ ├── base.py # Base service
│ │ ├── auth.py # Authentication business logic
│ │ ├── user.py # User business logic
│ │ ├── book.py # Book business logic
│ │ ├── category.py # Category business logic
│ │ └── order.py # Order business logic
│ │
│ └── main.py # FastAPI application entry point
│
├── tests/
│ ├── conftest.py
│ ├── unit/
│ │ └── test_security.py
│ ├── api/
│ │ ├── test_auth.py
│ │ ├── test_users.py
│ │ ├── test_books.py
│ │ ├── test_categories.py
│ │ └── test_orders.py
│ └── integration/
│ ├── conftest.py
│ ├── test_auth_service.py
│ ├── test_book_service.py
│ ├── test_category_service.py
│ └── test_order_service.py
│
├── .env.example
├── .gitignore
├── alembic.ini
├── docker-compose.yml
├── pyproject.toml
├── Dockerfile
├── pytest.ini
├── README.md
└── requirements.txt
# Clone repository
git clone https://github.com/badly-juice/Book_Store_API
# Start container
docker compose up --build -dFollow container logs:
docker compose logs -fA local run is possible when PostgreSQL is installed and available separately.
# Create virtual environment
python -m venv .venvActivate virtual environment:
# Windows
.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activateInstall dependencies:
pip install -r requirements.txtConfigure .env.example, apply migrations, and start the application:
# Apply migrations
alembic upgrade head
# Start the application
uvicorn app.main:app --reloadSwagger UI:
http://localhost:8000/docs
ReDoc:
http://localhost:8000/redoc
OpenAPI schema:
http://localhost:8000/openapi.json
| Method | Endpoint | Description | Access |
|---|---|---|---|
| POST | /api/v1/auth/register |
Register a new user | All |
| POST | /api/v1/auth/login |
Authenticate a user and return access and refresh tokens | All |
| POST | /api/v1/auth/refresh |
Issue a new access/refresh token pair | Authorized |
| Method | Endpoint | Description | Access |
|---|---|---|---|
| GET | /api/v1/users/ |
Get all users | Administrator |
| GET | /api/v1/users/me |
Get the current user's profile | Authorized |
| GET | /api/v1/users/{user_id} |
Get a user by ID | Administrator |
| PATCH | /api/v1/users/me |
Update the current user's profile | Authorized |
| PATCH | /api/v1/users/{user_id} |
Update a user's profile | Administrator |
| Method | Endpoint | Description | Access |
|---|---|---|---|
| GET | /api/v1/books/ |
Get all books with their categories | All |
| GET | /api/v1/books/{book_id} |
Get a single book | All |
| POST | /api/v1/books/ |
Create a book | Administrator |
| PATCH | /api/v1/books/{book_id} |
Update a book | Administrator |
| DELETE | /api/v1/books/{book_id} |
Delete a book | Administrator |
| Method | Endpoint | Description | Access |
|---|---|---|---|
| GET | /api/v1/categories/ |
Get all categories | All |
| GET | /api/v1/categories/{category_id} |
Get a single category | All |
| POST | /api/v1/categories/ |
Create a category | Administrator |
| PATCH | /api/v1/categories/{category_id} |
Update a category | Administrator |
| DELETE | /api/v1/categories/{category_id} |
Delete a category | Administrator |
| Method | Endpoint | Description | Access |
|---|---|---|---|
| GET | /api/v1/orders/ |
Get orders available to the current user | Authorized |
| GET | /api/v1/orders/{order_id} |
Get a single order with its items | Authorized |
| POST | /api/v1/orders/ |
Create a new pending order | Authorized |
| POST | /api/v1/orders/{order_id}/items |
Add a book to an existing pending order | Authorized |
| POST | /api/v1/orders/{order_id}/cancel |
Cancel an eligible order and restore stock | Authorized |
curl -X POST http://localhost:8000/api/v1/auth/register \
-H "Content-Type: application/json" \
-d '{"name": "Alice", "email": "[email protected]", "password": "Password123!"}'curl -X POST http://localhost:8000/api/v1/auth/login \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "[email protected]&password=Password123!"curl -X POST "http://localhost:8000/api/v1/auth/refresh?refresh_token=<refresh-token>"curl http://localhost:8000/api/v1/books/curl http://localhost:8000/api/v1/orders/ \
-H "Authorization: Bearer <access-token>"curl -X POST http://localhost:8000/api/v1/orders/ \
-H "Authorization: Bearer <access-token>"curl -X POST http://localhost:8000/api/v1/orders/<order-uuid>/items \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <access-token>" \
-d '{"book_id": "<book-uuid>", "quantity": 2}'curl http://localhost:8000/api/v1/orders/<order-uuid> \
-H "Authorization: Bearer <access-token>"curl -X POST http://localhost:8000/api/v1/orders/<order-uuid>/cancel \
-H "Authorization: Bearer <access-token>"# Install dependencies
pip install -r requirements.txt
# Start tests
pytestWarning: The integration tests clear the database after each test. Run the test suite only against a dedicated development/test database. Do not run it against a production database or any database containing important data.
| Variable | Description | Default |
|---|---|---|
DATABASE_URL |
Async PostgreSQL connection string | postgresql+asyncpg://postgres:postgres@localhost:5432/bookstore |
SECRET_KEY |
Secret key used for JWT signing | dev-secret-key |
ALGORITHM |
JWT signing algorithm | HS256 |
ACCESS_TOKEN_EXPIRE_MINUTES |
Access token lifetime | 30 |
REFRESH_TOKEN_EXPIRE_DAYS |
Refresh token lifetime | 7 |
Don't use the exact names defined in
.env.example. Never commit real secrets or database credentials.
# Create new migrations
alembic revision --autogenerate -m "description"
# Apply migrations
alembic upgrade head
# Rollback one migration
alembic downgrade -1
# Show migrations history
alembic history
# Check the current revision
alembic currentAlembic is configured to work with the application's asynchronous SQLAlchemy setup.
The API uses access and refresh tokens. A refresh endpoint allows clients to obtain a new token pair without repeating the login flow.
Two roles are supported:
USER— regular authenticated userADMIN— administrator with access to management operations
- Create an order.
- Add one or more books to the order.
- The server checks stock availability and updates the order total.
- The order can then be cancelled if it is still in an eligible status.
Books can be associated with multiple categories through the book_categories association table.
Orders start in PENDING status. The server controls status and calculated financial fields instead of allowing clients to modify them directly.
Adding books to an order decreases stock. Cancelling an eligible order restores the reserved stock.
Critical inventory operations use row-level locking to protect stock from conflicting concurrent updates.