SAFRS

Expose SQLAlchemy models as JSON:API resources and generate API documentation with minimal boilerplate.

SAFRS is built around SQLAlchemy models and JSON:API-style resource handling. The repository includes FastAPI and Flask adapters.

Start here

• Wiki home
• Installation
• Quickstart (Flask)
• Quickstart (FastAPI)
• Examples

Functionality

• JSON:API collection and instance endpoints for SQLAlchemy models
• relationship endpoints and include support
• filtering, sorting, pagination, sparse fieldsets, and bulk request support
• custom RPC methods with @jsonapi_rpc
• generated Swagger / OpenAPI documentation
• serialization hooks, computed attributes, and model-level customization
• stateless service-style endpoints through JABase

Install

SAFRS currently requires Python >=3.10.

Install from PyPI:

pip install safrs

Editable install from a clone:

git clone https://github.com/thomaxxl/safrs
cd safrs
python -m venv venv
source venv/bin/activate
pip install -e .

For the broader example set, including auth and admin examples:

pip install -r examples/requirements.txt

More setup details: Installation wiki page

Quick start from this repository

SAFRS models inherit both SAFRSBase and the SQLAlchemy model base. You then expose them with:

• SafrsApi(...).expose_object(Model) for Flask
• SafrsFastAPI(...).expose_object(Model) for the FastAPI adapter

Run the smallest Flask example:

python examples/mini_app.py

Run the smallest FastAPI example:

python examples/mini_fastapi_app.py

Quickstarts and walkthroughs:

• Quickstart (Flask)
• Quickstart (FastAPI)

Example files worth opening first

• examples/mini_app.py — smallest Flask example
• examples/demo_relationship.py — relationships and includes
• examples/mini_fastapi_app.py — smallest FastAPI example
• examples/demo_fastapi.py — fuller FastAPI demo
• examples/demo_pythonanywhere_com.py — broader Flask showcase
• examples/demo_stateless.py — stateless / non-SQLAlchemy-style resource example

The full examples index is in the wiki: Examples

Documentation map

Getting started:

• Installation
• Quickstart (Flask)
• Quickstart (FastAPI)

Core JSON:API behavior:

• JSON:API basics
• Relationships and includes
• Filtering
• Sorting, pagination, and sparse fieldsets
• Content types and errors
• Bulk requests

Customization and extension:

• RPC / custom methods
• HTTP methods and hooks
• Endpoint decorators
• Serialization and jsonapi_attr
• Security and access control
• Configuration reference

Advanced topics:

• Stateless endpoints / JABase
• Troubleshooting
• Docker / deployment
• Existing databases (legacy)

Notes

• Flask is still the main documented SAFRS path.
• The FastAPI adapter exists in the repository and is documented, but it should still be treated as experimental.
• The older expose-existing-database workflow is no longer the main recommended entry point and is kept as legacy documentation.

SAFRS originally stood for SqlAlchemy Flask-Restful Swagger. The project has since grown beyond the original Flask-only framing, but the historical name remains.