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, it includes FastAPI and Flask adapters.
Check out the Live Demo!
- JSON:API collection and instance endpoints for SQLAlchemy models
- relationship endpoints and
includesupport - 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
SAFRS currently requires Python >=3.10.
Install from PyPI:
pip install safrsEditable 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.txtMore setup details: Installation wiki page
SAFRS models inherit both SAFRSBase and the SQLAlchemy model base. You then expose them with:
SafrsApi(...).expose_object(Model)for FlaskSafrsFastAPI(...).expose_object(Model)for the FastAPI adapter
Run the smallest Flask example:
python examples/mini_app.pyRun the smallest FastAPI example:
python examples/mini_fastapi_app.pyQuickstarts and walkthroughs:
examples/mini_app.py— smallest Flask exampleexamples/demo_relationship.py— relationships and includesexamples/mini_fastapi_app.py— smallest FastAPI exampleexamples/demo_fastapi.py— fuller FastAPI demoexamples/demo_pythonanywhere_com.py— broader Flask showcaseexamples/demo_stateless.py— stateless / non-SQLAlchemy-style resource example
The full examples index is in the wiki: Examples
Getting started:
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:
- 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.