This template is created to jump-start your API development by providing the setup from a real-world project! This template utilizes the following tech stack:
- π Python v3.12.1 or higher.
- β‘οΈ FastAPI as the main web framework.
- π¦ Uvicorn for the web server.
- π³ Docker for containerization.
- π GitHub Actions for the CI.
With your localhost, you can find all endpoints after the api/
prefix. The first page is the api health checker to show you if your server is running properly.
- API health checker
$Λ\rightarrow$ http://localhost:8000/api/
. - API Documentation
$Λ\rightarrow$ http://localhost:8000/docs/
.
with Docker, you just change the host into 0.0.0.0
:
- API health checker
$Λ\rightarrow$ http://0.0.0.0:8000/api/
. - API Documentation
$Λ\rightarrow$ http://0.0.0.0:8000/docs/
.
Lean speed!
-
FastAPI is crowned as the fastest web framework for Python and thus we use it for our backend development.
-
Uvicorn fills the gap for low-level server/application interface for Python's asynchronous frameworks such as FastAPI.
-
Docker is a technology that packages an application into standardized units called containers that have everything the software needs to run including libraries, system tools, code, and runtime.
-
GitHub Actions provide a comprehensive method to setup our continuous integration and deployment.
There are other technologies utilized in this project template to ensure that your application is robust and provides the best possible development environment for your team!
-
TOML
$\rightarrow$ It provides a signle source of configuration for your project! -
PyEnv
$\rightarrow$ The simplest way to manage our Python version. -
Pyenv-VirtualEnv
$\rightarrow$ The plugin forPyenv
to manage the virtual environment for our packages. -
Pre-Commit
$\rightarrow$ Git hook scripts to identify issues and quality of your code before pushing it to GitHub. -
Pre-Commit CI
$\rightarrow$ Continuous integration for our Pre-Commit hook that fixes and updates our hook versions. -
Black (Python)
$\rightarrow$ Manage your Python code style with auto-formatting. -
Isort (Python)
$\rightarrow$ Sort yourimport
for clarity. Also for Python. -
MyPy (Python)
$\rightarrow$ A static type checker for Python that helps you to write cleaner code. -
PyTest
$\rightarrow$ The testing framework for Python code. -
CODEOWNERS
$\rightarrow$ A file for distributing the responsibilities in our project to each team/teammate. -
CodeCov
$\rightarrow$ A platform that analyzes the result of your software tests.
There are 2 ways to develop your project. The first way is with your local environment. This is totally fine but it would be quite complex if youh have a bigger team where everyone uses a different operating system. Hence I prepare the Docker scripts in docker/
that you can execute so everyone will use the same operating system that is defined in the Docker virtual machine (container) via my script. Both ways will be prepared in the following steps:
-
Python project setup:
# Creating VENV pyenv virtualenv 3.12.1 <YOUR_ENV_NAME> pyenv local <YOUR_ENV_NAME> # Install dependencies pip3 install -r requirements.txt # Test run your backend server uvicorn src.main:app --reload
-
Testing with
PyTest
:# For testing without Docker pytest -vv # For testing within Docker docker exec app pytest -vv
-
Pre-Commit
setup:# Make sure you are in the ROOT project directory pre-commit install pre-commit autoupdate # To execute pre-commit run
-
Credentials setup: If you are not used to VIM or Linux CLI, then ignore the
echo
command and do it manually. All the secret variables for this template are located in.env.example
.If you want to have another name for the secret variables, don't forget to change them also in:
.github/workflows/ci.yaml
backend/src/config.py
docker-compose.yaml
# Make sure you are in the ROOT project directory touch .env echo "SECRET_VARIABLE=SECRET_VARIABLE_VALUE" >> .env
-
CODEOWNERS
setup: Go to.github/
and openCODEOWNERS
file to assign any type of tiles to your team members. -
Docker setup:
docker-compose build docker-compose up # Every time you write a new code, update your container with: docker-compose up -d --build
-
Go to https://about.codecov.io/, and sign up with your github to get the
CODECOV_TOKEN
for your repository. -
Go to your GitHub repository and register all the credentials in
.env.example
repository settings (settings
$\rightarrow$ (scroll down a bit)Secrets
$\rightarrow$ Actions
$\rightarrow$ New repository secret
)
βββ .github/
βββ ISSUE_TEMPLATE/ # Directory for collaboration templates.
βββ bug_report.md # Module to follow when reporting bugs.
βββ feature_request.md # Module to follow when requesting features.
βββ workflows/ # Directory for continuous operations: CI/CD.
βββ ci.yaml # Module for CI.
βββ CODEOWNERS # Module to distribute code ownership.
βββ coverage/ # Directory for test coverage reports.
βββ docker/
βββ docker-compose.yaml # Module for docker compose.
βββ Dockerfile.dev # Module for docker container in development.
βββ Dockerfile.prod # Module for docker container in production.
βββ src/
βββ api/
βββ routes/ # Directory for routes.
βββ api_health.py # Module for API health checker.
βββ endpoints.py # Module for all routes.
βββ core/
βββ config.py # Module for application settings.
βββ events.py # Module for in-app event registration.
βββ logger.py # Module for custom logging system.
βββ models/
βββ domain/ # Directory for all domain models.
βββ schema/ # Directory for schema models.
βββ base.py # Module with base class for schema models.
βββ utils/
βββ formatter.py # Module with formatters.
βββ main.py # Module with application class.
βββ tests/
βββ integration_tests/ # Directory for integration tests.
βββ routes/ # Directory for testing all routes.
βββ api_health_py # Module that tests health checker endpoint.
βββ unit_tests/ # Directory for unit tests.
βββ test_src_version.py # Module that tests the `src/` version.
βββ conftest.py # Module for test configuration.
βββ .dockerignore # Module with docker ignore list.
βββ .env.example # Module with secret names (rename to .env).
βββ .gitignore # Module with git ignore list.
βββ .pre-commit-config.yaml # Module for safeguarding commit message.
βββ LICENSE.md # Module with license type (to be deleted).
βββ codecov.yaml # Module for Codecov configuration.
βββ pyproject.toml # Module for project configuration.
βββ README.md # Module for project documentation.
βββ requirements.txt # Module with python packages.
Happy engineering and never stop innovating! For feedback, bug reports, or feature requests, please use the issue template and create an issue so we can tackle it as a community!