SAFRS: Python OpenAPI & JSON:API Framework
Expose SQLAlchemy models as JSON:API resources with auto-generated OpenAPI documentation for Flask and FastAPI.
What is SAFRS: Python OpenAPI & JSON:API Framework?
SAFRS is a Python library that automatically generates JSON:API-compliant REST APIs from SQLAlchemy models. It solves the problem of writing repetitive boilerplate code for CRUD operations by providing ready-to-use endpoints with filtering, sorting, pagination, and relationship handling. The library also auto-generates OpenAPI/Swagger documentation, making API exploration and integration straightforward.
Backend developers building data-driven web services with Python, especially those using SQLAlchemy ORM and needing JSON:API compliance. It's ideal for teams wanting rapid API prototyping or maintaining consistent API standards.
Developers choose SAFRS because it dramatically reduces development time by automating API creation from existing SQLAlchemy models while ensuring strict JSON:API compliance. Its built-in OpenAPI documentation and support for both Flask and FastAPI provide flexibility without sacrificing standardization.
Overview
SqlAlchemy Flask-Restful Swagger Json:API OpenAPI
Use Cases
Best For
- Rapidly prototyping REST APIs from existing SQLAlchemy models
- Building JSON:API-compliant services with automatic documentation
- Creating consistent CRUD endpoints with filtering and pagination
- Developing data-driven applications with Flask or FastAPI backends
- Exposing database relationships through standardized API includes
- Adding custom RPC methods alongside auto-generated endpoints
Not Ideal For
- Projects requiring stable, production-ready FastAPI integration, as the FastAPI adapter is explicitly marked experimental in the README
- Teams stuck on Python versions below 3.10, due to the library's strict version requirement
- Applications not using SQLAlchemy ORM, as SAFRS is fundamentally tied to SQLAlchemy models and cannot work with other data layers
- Developers needing highly customized API behavior that deviates from JSON:API standards, as SAFRS enforces strict compliance which limits flexibility
Pros & Cons
Pros
Handles serialization, relationships, filtering, sorting, and pagination according to JSON:API specs out of the box, drastically reducing boilerplate code for CRUD operations.
Generates Swagger/OpenAPI specifications directly from SQLAlchemy models, providing instant API exploration and integration without extra setup.
Supports both Flask and FastAPI through dedicated adapters, allowing developers to choose their preferred backend framework while maintaining JSON:API features.
Enables adding custom API endpoints beyond CRUD using the @jsonapi_rpc decorator, as shown in examples, for extending functionality without breaking JSON:API structure.
Offers @jsonapi_attr decorator for defining read-only or writable computed fields with metadata for documentation, enhancing serialization control per the wiki.
Cons
The FastAPI adapter is documented as experimental, meaning it may have bugs, lack features, or undergo breaking changes, making it risky for production use.
Heavily dependent on SQLAlchemy models; projects using other ORMs or raw SQL must refactor or cannot benefit, limiting adoption in diverse tech stacks.
Advanced features like stateless endpoints or deep serialization hooks require navigating extensive wiki documentation and decorators, increasing learning curve for non-standard cases.
As a specialized library, it has fewer community extensions, plugins, or third-party integrations compared to broader frameworks like Django REST, potentially slowing development.
Frequently Asked Questions
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.