This is a simple application that has a partial implementation of an online store's functionality. It was created to demonstrate how Domain Driven Design can be implemented using the following technologies:
- Python – programming language
- FastAPI – web framework
- Pydantic – library for creating models and validating them
- SQLAlchemy – ORM for working with a database
- Docker
- PostgreSQL
-
Create a database for the project.
-
Rename the
.env.examplefile to.env:cd simple_store mv .env.example .env -
Set the
DATABASE_URLin.env. IMPORTANT: TheDATABASE_URLmust start withpostgresql+asyncpg:. -
Apply the database dump.
psql -d <db_name> -f db_dumps/orders.sql
-
Navigate to the project directory:
cd simple_store -
Run the following command:
make docker-run
or alternatively, run:
docker run --network=host --env-file=.env workaccpy/simple_store:latest
IMPORTANT: The first time you run these commands, you must have an internet connection because the Docker image of the application is downloaded from Docker Hub.
FastAPI provides automatically generated and interactive documentation for API, making it easy to explore, test, and understand the available endpoints. Below are the key documentation tools available by default:
The Swagger UI is available at the /docs endpoint.
It offers an intuitive and interactive interface where you can:
- Visualize: See the structure of API, with all routes and their details neatly organized.
- Interact: Send requests to the API directly from the browser, testing endpoints without additional tools.
- Understand: Quickly grasp how the API works, with descriptions of each route, parameters, and expected responses.
At the /redoc endpoint, you will find ReDoc, a beautifully minimal and user-friendly documentation tool.
While it doesn’t provide the interactivity of Swagger UI, it excels in presenting:
- Clean design: ReDoc offers a structured and modern view of the API, making it easy to browse.
- Efficient navigation: ReDoc’s documentation is organized into collapsible sections, perfect for quickly finding specific endpoints.
The /openapi.json endpoint serves the complete OpenAPI schema for Simple Store application in JSON format.
This schema is a machine-readable representation of API, defining all endpoints, their parameters, request bodies, and responses.
It can be:
- Used by tools: Integrate API with tools that support OpenAPI for automation, code generation, and validation.
- A standard: As an OpenAPI-compliant schema, it provides a universal way to describe API for both humans and machines.
This schema powers both Swagger UI and ReDoc.
This section outlines the endpoints available for managing product categories, subcategories, and products. Each endpoint supports various operations, such as creation, listing, updating, and deleting, as well as handling reservations and sales.
- Description: Create a new product category.
- Purpose: Allows the addition of a new category to organize products.
- Description: Retrieve a list of all product categories.
- Purpose: Provides a comprehensive list of existing categories for browsing or selection.
- Description: Create a new product subcategory.
- Requirements: At least one category must be created before adding a subcategory.
- Purpose: Allows for further organization of products within an existing category.
- Description: Retrieve a list of all product subcategories.
- Purpose: Provides a comprehensive list of existing subcategories for browsing or selection.
- Description: Obtain a report on product sales.
- Purpose: Generates a detailed sales report based on specified filters.
- Description: Create a new product.
- Requirements: At least one category and one subcategory must exist before adding a product.
- Purpose: Allows the addition of a new product to the inventory.
- Description: Retrieve a list of products where the available quantity is greater than 0.
- Filters Supported:
- Categories
- Subcategories
- Pagination: Supports pagination with parameters:
- limit
- offset
- Purpose: Provides a comprehensive list of available products with filtering and pagination options.
- Description: Change the quantity of a product.
- Purpose: Adjusts the available quantity of a product and manages reservations accordingly.
- Description: Change the price of a product.
- Impact: The price is updated in all orders with the status "RESERVED."
- Purpose: Updates the price of a product and reflects this change in reserved orders.
- Description: Change the discount on a product.
- Impact: The discount is updated in all orders with the status "RESERVED."
- Purpose: Adjusts the discount for a product and updates it in reserved orders.
- Description: Delete a product from the inventory.
- Impact: All order history for the product is also deleted.
- Purpose: Permanently removes a product and its associated order history.
- Description: Reserve a product.
- Impact: Increases the reserved quantity and creates an order with the status "RESERVED."
- Purpose: Marks a product as reserved and adjusts its available quantity.
- Description: Cancel a product reservation.
- Impact: Decreases the reserved quantity and changes the order status to "CANCELLED."
- Purpose: Releases a reserved product and updates the order status.
- Description: Sell a product.
- Impact: Decreases the total product quantity and the reserved product quantity, changes the order status to "COMPLETED."
- Purpose: Finalizes the sale of a product and updates its quantity and order status.