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, it includes FastAPI and Flask adapters.

Check out the Live Demo!

Start here

• Wiki home
• 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)

Computed attributes with jsonapi_attr

Use @jsonapi_attr when you want a targeted computed field instead of a broad to_dict override.

• Getter-only @jsonapi_attr fields are serialized as read-only attributes. Request writes are rejected with a client validation error.
• Direct Python assignment to a getter-only or read_only=True computed attr raises AttributeError.
• Getter+setter @jsonapi_attr fields accept raw request values. Raise ValueError or TypeError in the setter to surface a client validation error.
• Optional parser= and validator= hooks can normalize or reject request values before the setter runs.
• @jsonapi_attr declared on mixins or base classes is inherited by SAFRS subclasses.
• Metadata from the decorator docstring YAML before --- can drive docs generation: description, default, swagger_type, and swagger_format.
• The decorator also accepts metadata kwargs directly, for example @jsonapi_attr(description=\"Count\", swagger_type=\"integer\").
• write_only=True keeps a computed attr in request schemas/examples while omitting it from serialized responses.
• FastAPI request schemas and examples include writable computed attrs but omit read-only ones; response schemas mark read-only attrs and omit write-only ones.

Examples:

• examples/mini_examples/ex03_jsonapi_attr.py
• examples/demo_fastapi.py
• examples/demo_pythonanywhere_com.py

See the detailed behavior contract in the wiki: Serialization and jsonapi_attr

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.