PerFact API Base

The main FastAPI package for the PerFact API. Provides authentication, authorisation, database session handling, and plugin discovery. All domain-specific API modules are in separate packages and loaded automatically at startup via entry points.

Applications

perfact.api.main.app — user-facing API

Hosts all plugins registered under the perfact.api entry point group. All routes are served under the /api path prefix. Users authenticate via a login cookie or an Authorization: Apikey … header. Access to individual endpoints can be restricted by role:

from perfact.api.main.auth import require_roles

@router.get("/my-endpoint")
@require_roles("MyRole")
def my_endpoint(session: DBSession) -> ...:
    ...

perfact.api.main.assignworker — task runner API

Hosts all plugins registered under the perfact.assignapi entry point group. All routes are served under the /assignworker path prefix. Intended for internal use by assignd. Authentication is HTTP Basic Auth with a pre-shared password hash configured in the YAML config file.

Plugin discovery

At startup, both apps iterate over their respective entry point group and call mount(app) on each discovered plugin:

INFO - start plugin discovery
INFO - try to include plugin: perfact.api.pd.routes:mount
INFO - finished discovery and include: 1 plugins

A plugin registers itself by declaring an entry point in its pyproject.toml:

[project.entry-points.'perfact.api']
myplugin = 'perfact.api.myplugin.routes:mount'

getting started as developer

After you checked out this repository, do the following steps to be able to debug your application:

1. create and activate venv

   python -m venv .venv
   
   source .venv/bin/activate # linux
   .venv/Scripts/Activate.ps1 # PowerShell
   

2. Install the API plugins you want to include without doing changes by installing them from pypi:

   pip install perfact-api-base
   

3. Install the API plugins you want to include and change in your instance by checking them out somewhere and installing/linking them into your application via pip install -e:

   pip install -e ../perfact-api-base/ # required
   pip install -e ../perfact-api-app/app/ # required
   pip install -e ../perfact-api-pd-model/ # example
   

Hint: Every code change is available in the application after the next restart/reload. Changes to the entrypoints are available after the next install command execution (as this is recreating the ENTRYPOINTS-file belonging to the package in the site-packages folder).

You can install as much as plugins you like, even custom ones.

pip will automaticly check if more dependencies needed by the plugin while installing, e.g.

Requirement already satisfied: fastapi

Now you can run the application:

uvicorn perfact.api.main.app:app # run API for frontend
uvicorn perfact.api.main.assignworker:app # run API for assignd worker APIs
uvicorn perfact.api.main.app:app  --reload --reload-include ../ # run API for frontend with auto-reload for all editable dependencies

There is a launch.json-file provided to debug the application in VS Code. To use that, you have to create a configuration file (see below).

Configuration

The application can be configured by providing a configuration yaml-File containing informations about the database connection and basic auth credentials (for assignworker). The configuration file is given to the application by providing the location (absolute or relative to working dir) in the environment variable PERFACT_API_CONFIG_PATH.

Example:

connstr: postgresql+psycopg://zope@/perfactema # default, can be left out
basicauth: "$argon2id$v=19$m=65536,t=3,p=4$6itEouPTNwWEXDKScKmMrw$NwhN1vAUN8EZjC62HrtXjx7n+K1Mujjd/QqioaHvyOg" # password=test

Dependencies

• perfact-api-app
• fastapi
• sqlalchemy
• psycopg[c]
• argon2-cffi
• pydantic-settings

Maintainers

• Viktor Dick viktor.dick@perfact.de
• Alexander Rolfes alexander.rolfes@perfact.de