flarchitect 0.1.2

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 in minutes while keeping you in full control of your models and endpoints. 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, saving you time without sacrificing quality or customisation.

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.
• GraphQL integration – expose your models through a single /graphql endpoint when you need more flexible queries.

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

Authentication

flarchitect ships with ready-to-use JWT, Basic and API key authentication. Choose strategies with API_AUTHENTICATE_METHOD.

JWT

app.config["API_AUTHENTICATE_METHOD"] = ["jwt"]
app.config["ACCESS_SECRET_KEY"] = "access-secret"
app.config["REFRESH_SECRET_KEY"] = "refresh-secret"
app.config["API_USER_MODEL"] = User
app.config["API_USER_LOOKUP_FIELD"] = "username"
app.config["API_CREDENTIAL_CHECK_METHOD"] = "check_password"

Basic

app.config["API_AUTHENTICATE_METHOD"] = ["basic"]
app.config["API_USER_MODEL"] = User
app.config["API_USER_LOOKUP_FIELD"] = "username"
app.config["API_CREDENTIAL_CHECK_METHOD"] = "check_password"

API key

app.config["API_AUTHENTICATE_METHOD"] = ["api_key"]
app.config["API_KEY_AUTH_AND_RETURN_METHOD"] = lookup_user_by_token
# app.config["API_CREDENTIAL_HASH_FIELD"] = "api_key_hash"  # optional

See the authentication docs for full configuration details and custom strategies.

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, docs served at /docs

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

GraphQL

Prefer working with a single endpoint? flarchitect can turn your SQLAlchemy models into a GraphQL schema with just a couple of lines. Generate the schema and register it with the architect:

from flarchitect.graphql import create_schema_from_models

schema = create_schema_from_models([Item], db.session)
architect.init_graphql(schema=schema)

With the server running you can open GraphiQL at http://localhost:5000/graphql and explore your data interactively. Use the all_items query to fetch existing records:

query {
    all_items {
        id
        name
    }
}

The GraphQL demo contains ready-made models and sample queries to help you get started.

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

Running Tests

To run the test suite locally:

pip install -e .[dev]
export ACCESS_SECRET_KEY=access
export REFRESH_SECRET_KEY=refresh
pytest

The ACCESS_SECRET_KEY and REFRESH_SECRET_KEY environment variables are required for JWT-related tests. Adjust the export commands for your shell and operating system.

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 development dependencies are installed and linters and tests pass locally:

pip install -e .[dev]
ruff --fix .
export ACCESS_SECRET_KEY=access
export REFRESH_SECRET_KEY=refresh
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 LICENSE for details.