Relations 

Embedding related records 

Add 'embed' => true to a column to inline the full related record instead of a stub:

'columns' => [
    'color_id'   => ['groups' => ['list', 'show'], 'embed' => true],
    'categories' => ['groups' => ['list', 'show'], 'embed' => true],
],

In default mode, embed alone is enough — it does not trigger explicit mode:

'columns' => [
    'color_id' => ['embed' => true],
],

Response with embedded data:

{
    "color": {
        "@id": "/_api/colors/1",
        "@type": "Color",
        "uid": 1,
        "name": "Red",
        "hex": "#ff0000"
    },
    "categories": [
        {
            "@id": "/_api/sys-categories/5",
            "@type": "SysCategory",
            "uid": 5,
            "title": "News"
        }
    ]
}

Controlling recursion depth 

Control recursion depth with 'embed' => ['depth' => 2]. The default depth is 1.

'columns' => [
    'color_id' => ['embed' => ['depth' => 2]],
],

Multi-table group fields 

TCA type=group fields with multiple allowed tables store relations in the prefixed tablename_uid format (e.g. pages_1,sys_file_3). These fields support embedding just like single-table relations:

// TCA definition
'related_items' => [
    'label' => 'Related Items',
    'config' => [
        'type' => 'group',
        'allowed' => 'tx_myext_domain_model_article,tx_myext_domain_model_color',
    ],
],

// API resource configuration
'columns' => [
    'related_items' => ['groups' => ['list', 'show'], 'embed' => true],
],

The embedded response contains full objects from different tables, each with its own @type and fields:

{
    "related_items": [
        {
            "@id": "/_api/articles/201",
            "@type": "Article",
            "uid": 201,
            "title": "Related Article"
        },
        {
            "@id": "/_api/colors/1",
            "@type": "Color",
            "uid": 1,
            "name": "Red"
        }
    ]
}

Each referenced table is resolved to its registered API resource. When no resource is registered for a table, a default-mode config is synthesized automatically (all TCA columns exposed).

Bulk preloading is fully supported: collection requests issue one SELECT per referenced table regardless of how many parent rows exist, avoiding N+1 queries.

Writing nested objects 

When a create or update request contains a related record as an object (rather than a UID), TCA_API creates the child record in-line. The child table must have a registered resource in the API registry.

{
    "title": "My Article",
    "color_id": { "name": "Red" }
}

By default the child resource is looked up by the foreign table name from TCA. When multiple resources are registered for the same DB table, use the resourceName column option to pin the lookup to a specific resource:

'columns' => [
    'color_id' => [
        'groups'       => ['list', 'show', 'create', 'update'],
        'resourceName' => 'colors',   // look up "colors" resource, not by table
    ],
],

This also controls which resource's security.create role is enforced on the nested write and which resource's column config is used for validation.

Supported relation types