:zap: FastAPI API Template

This template provides a robust starting point for building APIs with FastAPI. It includes user authentication, CRUD operations, JWT token-based authentication, and PostgreSQL integration. The setup is streamlined with Docker and includes comprehensive documentation and testing tools.

:pushpin: Features

• :closed_lock_with_key: User authentication with basic login and Google Auth
• :busts_in_silhouette: User management with creation and CRUD operations
• :page_facing_up: Example endpoints for Posts, Users, and Votes
• :heartbeat: API healthcheck endpoint
• :key: JWT token-based authentication
• :gear: Middleware support
• :earth_americas: CORS configuration
• :memo: Comprehensive Swagger API documentation
• :elephant: PostgreSQL database integration
• :lock: Field encryption for sensitive data

:floppy_disk: Installation

[!IMPORTANT] Min Python version: 3.14

Clone this repo:

git clone https://github.com/ezeparziale/fastapi-api-template

Create virtual environment:

python -m venv env

Activate environment:

• Windows:

. env/scripts/activate

• Mac/Linux:

. env/bin/activate

Upgrade pip:

python -m pip install --upgrade pip

Install requirements:

pip install -r requirements-dev.txt

Install pre-commit:

pre-commit install

:wrench: Config

Create .env file. Check the example .env.example

:globe_with_meridians: Google Auth credentials:

Create your app and obtain your client_id and secret:

https://developers.google.com/workspace/guides/create-credentials

:lock: How to create a secret key:

openssl rand -base64 64

:closed_lock_with_key: How to create an encryption key:

To create an encryption key for securing sensitive data, you can use the generate_key.py script provided in the repository. Run the following command:

python generate_key.py

This will generate a secure encryption key.

:construction: Before first run:

Run docker-compose :whale: to start the database server

docker compose -f "compose.yaml" up -d --build adminer db

and init the database with alembic:

alembic upgrade head

:key: Create a self-signed certificate with openssl:

openssl req -x509 -newkey rsa:4096 -nodes -out cert.pem -keyout key.pem -days 365

:runner: Run

uvicorn app.main:app --reload --port 8000 --ssl-keyfile key.pem --ssl-certfile cert.pem

:rotating_light: Lint

Run linter and formatter

scripts/lint.sh

scripts/format.sh

:technologist: Coverage

Run coverage

coverage run -m pytest

coverage report --show-missing

coverage html

Or run all in one with:

scripts/coverage.sh

:test_tube: Test

Run pytest with coverage

coverage run -m pytest

or

scripts/test.sh

:hammer_and_wrench: Alembic

Alembic is used for database migrations. Below are some common commands to manage your database schema.

Autogenerate a revision

To autogenerate a new revision based on the changes detected in your models, run:

alembic revision --autogenerate -m "your message here"

Generate a blank revision

To create a blank revision for custom migrations, run:

alembic revision -m "your message here"

Upgrade the database

To apply the latest migrations and upgrade the database schema, run:

alembic upgrade head

Downgrade the database

To revert the last migration and downgrade the database schema, run:

alembic downgrade -1

After creating a revision, you can edit the generated script to define your custom migrations.

:bar_chart: Monitoring

This project includes a complete observability stack using Grafana, Loki, and Promtail.

:rocket: Setup

1. Start the monitoring stack:

   docker compose up -d grafana loki promtail
   

2. Access Grafana: Open http://localhost:3000 in your browser.

   • Default credentials: admin / admin

3. Add Loki Data Source:

   • Go to Connections > Data sources.
   • Click Add data source and select Loki.
   • Set the URL to: http://loki:3100.
   • Click Save & test.

:level_slider: Create Dashboard with Variables

To visualize logs efficiently, follow these steps to create a dashboard with a level filter:

1. Create a New Dashboard:
   • Click the + icon > Dashboard.
2. Add a Variable for Log Level:
   • Go to Dashboard Settings (gear icon) > Variables.
   • Click Add variable.
   • Name: level
   • Type: Custom
   • Custom options (Values separated by comma): TRACE,DEBUG,INFO,SUCCESS,WARNING,ERROR,CRITICAL
   • Click Apply.
3. Add a Logs Panel:
   • Add a new Visualization.
   • Select Loki as the data source.
   • Use the following LogQL query:

     {container="app"} | json | record_level_name =~ "$level" | line_format "{{.record_message}}"
     

   • This query filters logs by the app container, parses the JSON format, filters by the selected $level variable, and cleans up the output message.