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:
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.
http://localhost:8000/api/
.http://localhost:8000/docs/
.with Docker, you just change the host into 0.0.0.0
:
http://0.0.0.0:8000/api/
.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!
Pyenv
to manage the virtual environment for our packages.import
for clarity. Also for Python.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 open CODEOWNERS
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!