Quick Start¶

This guide walks you through building a minimal API with flarchitect. You’ll define your models, configure a Flask application, spin up the server, and test the endpoints.

Installation¶

Install the package via pip.

pip install flarchitect

Define your models¶

Define your models using SQLAlchemy. flarchitect automatically resolves the active database session, whether you’re using Flask-SQLAlchemy or plain SQLAlchemy, so no special get_session method is required.

from flask_sqlalchemy import SQLAlchemy
from sqlalchemy.orm import DeclarativeBase

class BaseModel(DeclarativeBase):
    pass

db = SQLAlchemy(model_class=BaseModel)

class Author(db.Model):
    __tablename__ = "author"

    class Meta:  # required for auto-registration; fields inside are optional
        # Optional docs grouping:
        # tag = "Author"
        # tag_group = "People/Companies"

This setup gives flarchitect access to your models. The library automatically locates the active SQLAlchemy session. For non-Flask setups, a custom session resolver can be supplied via API_SESSION_GETTER in the Flask config; see custom-session-getter for details.

Warning

The Meta inner class is required for automatic route generation and documentation. Models without Meta are ignored and will not have CRUD endpoints or entries in the docs until you add it. The tag and tag_group attributes are optional and only affect documentation grouping.

Configure Flask¶

from flask import Flask
from flarchitect import Architect

app = Flask(__name__)

app.config["API_TITLE"] = "My API"
app.config["API_VERSION"] = "1.0"
app.config["API_BASE_MODEL"] = db.Model

architect = Architect(app)

These settings tell flarchitect how to build the API and where to find your models.

Spin up the app¶

Run the development server to expose the generated routes.

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

Launching the server makes the automatically generated API available.

Test the endpoints¶

Use curl to call an endpoint and view the response.

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

Example response:

{
  "datetime": "2024-01-01T00:00:00.0000+00:00",
  "api_version": "0.1.0",
  "status_code": 200,
  "response_ms": 15,
  "total_count": 1,
  "next_url": null,
  "previous_url": null,
  "errors": null,
  "value": [
    {"id": 1, "name": "Test Author"}
  ]
}

This structured payload is produced by create_response() and shows the standard metadata flarchitect includes by default. To return a bare list, disable the metadata fields via the API_DUMP_* configuration options, for example:

From Model to API¶

Turn this:

class Book(db.Model):

    id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String(80), unique=True, nullable=False)
    author = db.Column(db.String(80), nullable=False)
    published = db.Column(db.DateTime, nullable=False)

Into this:

GET /api/books

{
  "datetime": "2024-01-01T00:00:00.0000+00:00",
  "api_version": "0.1.0",
  "status_code": 200,
  "response_ms": 15,
  "total_count": 10,
  "next_url": "/api/authors?limit=2&page=3",
  "previous_url": "/api/authors?limit=2&page=1",
  "errors": null,
  "value": [
    {
      "author": "John Doe",
      "id": 3,
      "published": "2024-01-01T00:00:00.0000+00:00",
      "title": "The Book"
    },
    {
      "author": "Jane Doe",
      "id": 4,
      "published": "2024-01-01T00:00:00.0000+00:00",
      "title": "The Book 2"
    }
  ]
}

Next steps¶

To secure the API and define user roles, see Authentication and the Defining roles section.