Custom Serialisation

flarchitect controls how relationships are represented in responses through a configurable serialisation mode. You can set a global default and override it per request.

Serialisation modes

Set the default with API_SERIALIZATION_TYPE (globally or per‑model):

  • url (default): relationships render as URLs (stable, compact).

  • json: relationships always render as nested objects.

  • dynamic: only relationships listed in join render as nested objects; all others remain URLs.

  • hybrid: to‑one relationships render as nested objects; collections render as URLs.

Per‑request override

Clients can override the mode with a dump query parameter. Invalid values are ignored and the configured default is used.

Examples:

# dynamic serialisation for this request only
GET /api/invoices?dump=dynamic&join=invoice-lines,payments,customer

# always nest all relations
GET /api/books?dump=json

Depth and relation inclusion

Two additional knobs affect what appears in the output:

  • API_ADD_RELATIONS (default True) controls whether relationships are included at all.

  • API_SERIALIZATION_DEPTH (default 0) limits how many levels render as nested JSON. When 0, relationships remain URLs even if dump is json/hybrid, and dump=dynamic falls back to URLs unless a join explicitly names the relationship. Increase to nest that many levels before falling back to URLs.

Tip: For dashboards or detail views, dump=dynamic with join targets keeps payloads small while still embedding the specific related objects you need, even when the global depth is zero.