This is a generic application that is built with the intention of providing a thoughtfully designed, detailed, and approachable example of an API implementation using FastAPI. This project focuses on demonstrating tangible solutions for the functionality most often needed when implementing a new API, with the goal of providing the members of the Python and FastAPI communities with yet another reference point for enhancing their own implementations.

Here are a few quick facts about what you'll find in this project:

• FastAPI: Web Framework

• Gino: Async SQL ORM

• TimescaleDB: Timescale (Postgres) database -Typer & Click: CLI implementation

• Authentication with OAuth2+JWT: Both password and client_credentials flows are implemented.

  • See auth helpers and the access-token endpoint

• Python >=3.8.0
• Poetry Package Manager
• Docker

• jq brew install jq
• make brew install make
• httpie brew install httpie

Environment variables can either be defined at the system level or in a filed named '.env' in the project's root directory.

Example .env file for local development:

# .env
PYTHONPATH=./:./src/sunstruck:./src:${PYTHONPATH}

ENV=development

DATABASE_NAME=sunstruck
DATABASE_USERNAME=sunstruck
DATABASE_PASSWORD=password
DATABASE_HOST=0.0.0.0
DATABASE_PORT=5432

LOG_LEVEL=20
LOG_FORMAT=simple
DEBUG=false
SECRET_KEY=local

# master account credentials
MASTER_EMAIL=user@example.com
MASTER_PASSWORD=password

# for timescaledb container
POSTGRES_USER=sunstruck
POSTGRES_PASSWORD=password

1. Install Poetry: pip3 install poetry
2. Install the project dependencies defined in pyproject.toml: poetry install
3. Source your .env file if your IDE/terminal doesn't do so automatically: source .env
4. Optional: Populate the database with sample data sample data: poetry run seed_db
5. Launch the application and its supporting components: docker-compose up.
   • By default, the app will be served at http://0.0.0.0:8000.

• If you need to startover with a clean database, you can generate a fresh one by running sunstruck db recreate && seed_db or make recreate-and-seed-db.

Several frequently needed and useful commands are captured in the Makefile.

You can verify you have installed the project by running:

>>> sunstruck --help
Usage: sunstruck [OPTIONS] COMMAND [ARGS]...

  sunstruck API

Options:
  --help  Show this message and exit.

Commands:
  db      Database Management
  routes  List api routes
  run     Execution procedures

If you get an error saying the app can't be found, make sure the Poetry virtual environment is active (poetry shell)

# Application Control Commands
sunstruck run dev
sunstruck run web

# Information Display Commands
sunstruck routes

# Database Management Commands
sunstruck db downgrade
sunstruck db migrate
sunstruck db recreate
sunstruck db upgrade

The API documentation is viewable at http://0.0.0.0:8000/docs when the app container is running.

You can verify the API is available by checking the health endpoint:

curl http://0.0.0.0:8000/api/v1/health

All examples below will use HTTPie.

The database schema is managed by the application through a combination of SQLAlchemy and Alembic. The schema migrations produced by Alembic can be found here.

• Batch POSTing endpoint

  • Generate/view client credentials in user profile

  • A user account can be tied to multiple client credentials (max 10)

  • Social login (google, twitter, github)

  • More intuitive pagination

    • Can the response be modified from inside the dependency (e.g. adding headers)?

  • Filtering abstraction

• Rate Limiting

• Cache headers

• Field selection parameters

• Migrate to sqlalchemy 1.4/2.0
• Add Row Level Security / Row Ownership

• Update httpx dispatchers to >v11
• Create testing-only database models

• Convert config to Pydantic?

• Refactor util.jsontools to jsonlib

• Logging config file to configure levels by logger

• Add Grafana container

Many pieces of this codebase have been inspired by various projects in the FastAPI community:

• Tiangolo's Full-Stack-FastAPI-Postgresql
• FastAPI-React
• FastAPI-Contrib