Abstract models and @type

What this is about

Sometimes a thing comes in several kinds that have a lot in common, but not everything. A customer can be a private customer (with a date of birth) or a business customer (with a commercial register number). Both have a name, an address and orders.

That is what abstract models are for: a parent model with the shared fields and several concrete child models that inherit from it.

classDiagram
    class kunde {
        <<abstract>>
        name
        adresse
        auftraege
    }
    class privatkunde {
        geburtsdatum
    }
    class firmenkunde {
        handelsregisternummer
    }
    kunde <|-- privatkunde
    kunde <|-- firmenkunde

The type: @type

Every object carries its concrete type. In the database it is stored in the _MODELTYPE column; in JSON it is called @type. The value is the API path of the child model with dots instead of slashes:

The hub API: one entrance, several targets

For the abstract model, the generator creates a hub API with the usual paths, here /api/rest/crm/kunde/…. It does nothing itself; it forwards every request to the API of the right subtype. Each subtype also has its own normal API.

flowchart LR
    C(["Client"]) --> H["Hub API<br/>/crm/kunde"]
    H -->|"@type = crm.privatkunde"| P["API<br/>/crm/privatkunde"]
    H -->|"@type = crm.firmenkunde"| F["API<br/>/crm/firmenkunde"]
    C -.->|directly| P
    C -.->|directly| F

Where the hub API gets the type from depends on the operation:

Every operation step by step

Searching across all subtypes: two phases

A search on the hub API has to return objects of different types in one list, correctly sorted and paged. That happens in two phases:

sequenceDiagram
    participant C as Client
    participant H as Hub API /crm/kunde
    participant DB as Database
    participant P as API privatkunde
    participant F as API firmenkunde
    C->>H: POST /query (filter, sorting, page)
    Note over H,DB: Phase 1: only IDs and types
    H->>DB: SELECT id, _MODELTYPE ... WHERE ... ORDER BY ... LIMIT
    DB-->>H: [ (id1, private), (id2, business) ] + totalCount
    Note over H,F: Phase 2: read each row through its subtype
    par in parallel
        H->>P: read id1
    and
        H->>F: read id2
    end
    P-->>H: object 1
    F-->>H: object 2
    H-->>C: data in the order of phase 1 + meta

Permissions and filters

Each subtype is a complete model with roles of its own. Whoever reads through the hub API therefore needs the read permissions of the subtype the object belongs to. Attribute filters of the parent model automatically apply to all subtypes as well: a subtype is never a way around the rules of the parent model.

In the database

The parent model has a table of its own with the shared fields and the _MODELTYPE column. Each subtype has its own table with its additional fields, linked through the same id.

The company is stored with its own fields in the firmenkunde table.

Pitfalls