SQLAlchemy Models

flarchitect builds APIs directly from your SQLAlchemy models. To expose a model:

• Inherit from your configured base model.

• Add a Meta inner class (required for auto‑registration). Optionally include tag and tag_group to influence how endpoints are grouped in the docs.

• Define your fields and relationships as you normally would; nested relationships are handled automatically.

Example:

class Author(BaseModel):
    __tablename__ = "author"

    class Meta:
        tag = "Author"
        tag_group = "People/Companies"

    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(80))

That’s all that’s required to make the model available through the generated API.

Warning

Models without a Meta inner class are not auto‑registered. They will be ignored by route generation and will not appear in the documentation. The tag and tag_group attributes are optional; add them if you want to control documentation grouping.

Dump types

flarchitect can serialise model responses in different formats, controlled by API_SERIALIZATION_TYPE or Meta.serialization_type. Supported dump types are:

• url (default) – represent related objects only by their URL links.

• json – embed related objects as JSON objects.

• dynamic – choose between url and json using the dump query parameter.

• hybrid – include both URL links and embedded JSON for related objects.

Example:

class Config:
    API_SERIALIZATION_TYPE = "json"

Clients can override dynamic dumps per request with ?dump=url or ?dump=json.

Nested relationship dumping

API_ADD_RELATIONS controls whether relationship fields are included in the serialised response. Disable it to return only column data, or use ?dump_relationships=false on a request to temporarily suppress all relationships.

API_SERIALIZATION_DEPTH limits how many levels of related resources are embedded. 0 (default) keeps them as URLs even with dump=json or dump=dynamic. Increase the depth to inline that many relationship levels before falling back to URLs.

For API_SERIALIZATION_TYPE set to "dynamic", clients can choose which relationships to embed by supplying a comma-separated join parameter, e.g. ?join=books,publisher. Any relationships not listed are returned as URLs.

Example responses

URL-only dump (depth 1):

GET /api/authors/1
{
    "id": 1,
    "name": "Alice",
    "books": "/api/authors/1/books"
}

JSON dump (depth 1):

GET /api/authors/1?dump=json
{
    "id": 1,
    "name": "Alice",
    "books": [
        {"id": 10, "title": "Example", "publisher": "/api/publishers/5"}
    ]
}

JSON dump (depth 2 with API_SERIALIZATION_DEPTH = 2 or ?join=books,publisher):

GET /api/authors/1?dump=json
{
    "id": 1,
    "name": "Alice",
    "books": [
        {"id": 10, "title": "Example", "publisher": {"id": 5, "name": "ACME"}}
    ]
}

Hybrid dump:

GET /api/authors/1?dump=hybrid
{
    "id": 1,
    "name": "Alice",
    "books": "/api/authors/1/books",
    "publisher": {"id": 5, "name": "ACME"}
}