Home

SAFRS

SAFRS exposes SQLAlchemy models as a JSON:API service and generates API documentation for the exposed resources.

• Applies to: Flask and FastAPI
• Simple examples: examples/mini_app.py, examples/mini_fastapi_app.py
• Related pages: Installation, Quickstart (Flask), Quickstart (FastAPI), Examples

Choose your path

• Start with Quickstart (Flask) if you want to use Flask.
• Start with Quickstart (FastAPI) if you want the experimental FastAPI adapter and FastAPI-native docs.

Core topics

• JSON:API Basics for the endpoint model SAFRS creates for each exposed resource.
• Relationships and Includes for relationship URLs, include, and hidden relationships.
• Filtering for filter[attribute], JSON filter=..., and customization hooks.
• Sorting, Pagination, and Sparse Fieldsets for sort, page[...], fields[...], and exclude.
• Content Types and Errors for JSON:API media types, error envelopes, and common status codes.
• Bulk Requests for collection requests that send multiple resource objects in one payload.

Customization topics

• Customization is the hub page for serialization, methods, decorators, docs generation, and configuration.
• RPC / Custom Methods covers @jsonapi_rpc methods.
• Security and Access Control covers decorators, permission hooks, and auth-related examples.

Advanced topics

• Stateless Endpoints / JABase
• Performance
• Existing Databases (Legacy)
• Docker / Deployment
• Troubleshooting

Notes on framework status

• Flask is still the main documented path and the reference behavior.
• FastAPI support exists in the repository and is documented here, but it should still be treated as experimental unless the maintainer says otherwise.