Getting Started Sample Project

Flarchitect ships with a tiny demo that shows how it turns a SQLAlchemy model into a REST API. The sample lives in demo/quickstart/load.py and defines a single Author model. Running the script starts a local server and exposes the model at /api/authors, returning an empty list until you add data.

 1import datetime
 2
 3from flask import Flask
 4from flask_sqlalchemy import SQLAlchemy
 5from sqlalchemy import Date, Integer, String, Text
 6from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 7
 8from flarchitect import Architect
 9
10
11# Create a base model that all models will inherit from. This is a requirement for the auto
12# API creator to work. Don't, however, add to any of your models when using
13# flask-sqlalchemy; instead, inherit from `db.model` as you would normally.
14class BaseModel(DeclarativeBase):
15    """Base declarative model for all SQLAlchemy models."""
16
17
18# Create a new flask app
19app = Flask(__name__)
20
21# Create a new instance of the SQLAlchemy object and pass in the base model you have created.
22db = SQLAlchemy(model_class=BaseModel)
23
24# Set the database uri to an in memory database for this example.
25app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///:memory:"
26
27# Set the required fields for flarchitect to work.
28app.config["API_TITLE"] = "My API"
29app.config["API_VERSION"] = "1.0"
30app.config["API_BASE_MODEL"] = db.Model
31
32
33# Create a new model that inherits from db.Model
34class Author(db.Model):
35    """Model representing an author."""
36
37    __tablename__ = "author"
38
39    class Meta:
40        # all models should have class Meta object and the following fields which defines how the model schema's are
41        # references in redocly api docs.
42        tag_group = "People/Companies"
43        tag = "Author"
44
45    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
46    first_name: Mapped[str] = mapped_column(String)
47    last_name: Mapped[str] = mapped_column(String)
48    biography: Mapped[str] = mapped_column(Text)
49    date_of_birth: Mapped[datetime] = mapped_column(Date)
50    nationality: Mapped[str] = mapped_column(String)
51    website: Mapped[str | None] = mapped_column(String)
52
53
54with app.app_context():
55    # initialise the database with the app context
56    db.init_app(app)
57    # create the database tables
58    db.create_all()
59    # initialise the Architect object with the app context
60    Architect(app)
61
62# Run the app
63if __name__ == "__main__":
64    app.run(debug=True)
65
66# To access the API documentation, navigate to http://localhost:5000/docs

Run the demo

python demo/quickstart/load.py
curl http://localhost:5000/api/authors

The curl command answers with a JSON payload that includes some metadata and a value list of authors. Because the demo starts with no records, that list is empty:

{
    "total_count": 0,
    "value": []
}

Pop open http://localhost:5000/docs in your browser to explore the automatically generated API docs. To optionally restrict access, set the API_DOCUMENTATION_PASSWORD environment variable or enable API_DOCUMENTATION_REQUIRE_AUTH. When protection is active, navigating to /docs displays a login screen that accepts either the configured password or valid user credentials.