flarchitect 0.1.0.1

Automatic RESTful API generator with redoc

flarchitect

flarchitect is a friendly Flask extension that turns your SQLAlchemy or Flask-SQLAlchemy models into a production-ready REST API with almost no boilerplate. It automatically builds CRUD endpoints, generates interactive Redoc documentation and keeps responses consistent so you can focus on your application logic.

Why flarchitect?

If you're new here, welcome! flarchitect gets you from data models to a fully fledged REST API in minutes, letting you focus on the features that matter rather than plumbing.

Features

• Automatic CRUD endpoints – expose SQLAlchemy models as RESTful resources with a simple Meta class.
• Interactive documentation – Redoc or Swagger UI generated at runtime and kept in sync with your models.
• Built-in authentication – JWT, basic and API key strategies ship with a ready‑made /auth/login endpoint, or plug in your own.
• Extensibility hooks – customise request and response flows.
• Soft delete – hide and restore records without permanently removing them.

Optional extras

• Rate limiting & structured responses – configurable throttling and consistent response schema.
• Field validation – built-in validators for emails, URLs, IPs and more.
• Nested writes – send related objects in POST/PUT payloads when API_ALLOW_NESTED_WRITES is True.
• CORS support – enable cross-origin requests with API_ENABLE_CORS.

Installation

flarchitect supports Python 3.10 and newer. Set up a virtual environment, install the package and verify the install:

python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate
pip install flarchitect
python -c "import flarchitect; print(flarchitect.__version__)"

The final command prints the version number to confirm everything installed correctly.

Quick Start

from flask import Flask
from flarchitect import Architect
from models import Author, BaseModel  # your SQLAlchemy models

app = Flask(__name__)
app.config["API_TITLE"] = "My API"
app.config["API_VERSION"] = "1.0"
app.config["API_BASE_MODEL"] = BaseModel
app.config["API_ALLOW_NESTED_WRITES"] = True

architect = Architect(app)

if __name__ == "__main__":
    app.run(debug=True)

With the application running, try your new API in another terminal window:

curl http://localhost:5000/api/authors

OpenAPI specification

An OpenAPI 3 schema is generated automatically and powers the Redoc UI. You can switch to Swagger‑UI by setting API_DOCS_STYLE = 'swagger' in your Flask config. Either way you can serve the raw specification to integrate with tooling such as Postman:

from flask import Flask
from flarchitect import Architect

app = Flask(__name__)
architect = Architect(app)  # OpenAPI served at /openapi.json

The specification endpoint can be customised with API_SPEC_ROUTE. See the OpenAPI docs for exporting or customising the document.

Read about hiding and restoring records in the soft delete section.

Running Tests

To run the test suite locally:

pytest

Documentation & help

• Browse the full documentation for tutorials and API reference.
• Explore runnable examples in the demo directory, including a validators example showcasing email and URL validation.
• Authentication demos: JWT, Basic and API key snippets showcase the built-in strategies.
• Questions? Join the GitHub discussions or open an issue.
• See the changelog for release history.

Roadmap

Check out the project roadmap for upcoming features and enhancements.

Contributing

Contributions are welcome! For major changes, please open an issue first to discuss what you would like to change.

Before submitting a pull request, ensure that linters and tests pass locally:

ruff --fix .
pytest

Versioning & Releases

The package version is defined in pyproject.toml and exposed as flarchitect.__version__. A GitHub Actions workflow automatically publishes to PyPI when the version changes on master.

To publish a new release:

1. Update the version field in pyproject.toml (for example with hatch version patch).
2. Commit and push to master.

Ensure the repository has a PYPI_API_TOKEN secret with an API token from PyPI.

License

Distributed under the MIT License. See LICENCE for details.