What does it do? 

TCA_API is a TYPO3 extension that automatically generates a REST API from your TYPO3 TCA (Table Configuration Array) definitions. It exposes database tables as Hydra JSON-LD resources through a configuration-driven approach — no custom controllers or Extbase models needed.

By placing a simple PHP configuration file in your extension's Configuration/TcaApi/ directory, you get a fully functional REST API with CRUD operations, filtering, sorting, pagination, validation, and access control.

Motivation 

TYPO3 offers several existing approaches for serving content as structured data. TCA_API was built to fill a gap where other API extensions fall short: exposing multiple resources uniformly, with minimal boilerplate and strong query efficiency. See Motivation for the full comparison.

Features 

• Full CRUD — List, show, create, update (PUT & PATCH), and delete operations
• Hydra JSON-LD — Responses follow the Hydra specification (application/ld+json)
• Configuration-driven — Expose tables by registering a PHP configuration array; no custom controllers needed
• Serialization groups — Use groups to control which columns appear per operation (list, show, create, update)
• Filtering — Exact, partial, word-start, range, full-text search, and many-to-many filter strategies via query parameters; extensible via FilterInterface
• Sorting — Configurable allowed sort columns with defaults
• Pagination — Offset-based pagination with Hydra PartialCollectionView links
• Validation — Required, maxLength, minLength, and regex validators with structured 422 error responses
• Access control — Per-operation roles: PUBLIC, FE_USER, FE_GROUP, BE_USER, BE_ADMIN, OWNER (record-level ownership), or custom callable voters
• Virtual properties — Computed fields via callables or column processors, with support for referencing existing columns (including file/image columns at different sizes)
• Relation handling — Shallow stubs or fully embedded related records (configurable depth)
• Userinfo endpoint — Expose the authenticated FE user's own record at a configurable URL
• OpenAPI + Swagger UI — Auto-generated OpenAPI 3.0 spec and interactive Swagger UI served directly from the API prefix
• PSR-14 events — Hook into the request lifecycle with Before/AfterOperation and Before/AfterWrite events
• TYPO3 DataHandler — Write operations use TYPO3's DataHandler for safe, consistent data manipulation
• Extensible handler pipeline — Register custom operation handlers or override built-in ones from any extension

Current state 

Why existing approaches fall short 

How TCA_API solves this 

TCA_API takes a fundamentally different approach: raw SQL via QueryBuilder with bulk preloading and a zero-boilerplate configuration model.

1. No ORM, no object hydration. Records are raw associative arrays from ConnectionPool::getQueryBuilderForTable(). Zero overhead from property mapping, proxy objects, or lazy wrappers.

2. EmbedPreloader eliminates N+1 queries. Before serialization, the preloader scans all rows in a collection, collects every referenced foreign key, and executes one query per relation type — regardless of collection size:

   • hasOne FKs: SELECT * FROM colors WHERE uid IN (1, 2, 3)
   • hasMany MM: SELECT f.*, mm.uid_local FROM categories f JOIN mm ON ... WHERE mm.uid_foreign IN (...)
   • hasMany foreignField: SELECT * FROM children WHERE parent_id IN (...)
3. Fixed query count. The number of queries is 1 + R (one collection query + one per relation type), not 1 + N×R. Adding more rows to a page does not increase the query count.
4. Zero boilerplate per resource. A three-key PHP array is a complete resource definition — no domain model class, no repository, no controller, no routing config. Filtering, pagination, access control, and validation are declared in the same file.

Query count analysis 

The query-count difference between strategies is deterministic and can be derived from simple formulas:

• Naive N+1 / Extbase / t3api: Q = 1 + N × R
• TCA_API (EmbedPreloader): Q = 1 + R

Where N is the collection size and R is the number of embedded relation types per record.

These numbers are theoretical projections from the formula, not measurements from live extensions. Wall-clock impact depends on database round-trip latency, query complexity, and caching — all of which vary significantly between projects.

Comparison matrix 

(¹) The Record API's GreedyDatabaseBackend can reduce query count when related records share the same PID, so actual numbers may be lower in single-page contexts.

(²) EXT:headless query counts vary widely depending on TypoScript setup and DataProcessor configuration; the range reflects typical page-render workloads.

Call for feedback 

The comparison above is based on source-code reading and architectural reasoning. It has not been independently verified by developers experienced with EXT:t3api or EXT:nnrestapi, nor has it been validated against real-world production workloads.

If you work with these extensions and find that any claim is inaccurate, misleading, or missing important nuance — please open a GitHub Discussion or a pull request. Corrections are welcome, and the goal is an honest comparison rather than marketing copy.

Requirements 

Composer installation 

The extension is installed via Composer:

composer require maikschneider/tca-api

Site set setup 

TCA_API ships a TYPO3 site set (maikschneider/tca-api). Add it to your site configuration to activate the API.

In the TYPO3 backend, go to Site Management → Sites and add maikschneider/tca-api as a dependency, or edit your config/sites/<site>/config.yaml directly:

dependencies:
  - maikschneider/tca-api

Once the site set is active, the API is enabled and responds at the configured URL prefix (/_api/ by default). Site-level settings such as the API prefix, pagination defaults, CORS headers, and OpenAPI access can be customised in the TYPO3 backend under Site Management → Sites → Settings.

See Site Settings for all available options.

General 

API specification 

CORS 

General section 

The general key defines the basic resource properties:

return [
    'general' => [
        'table'        => 'tx_myext_domain_model_article',
        'resourceName' => 'articles',
        'resourceType' => 'Article',
        // operations defaults to ['list', 'show'] — omit for read-only resources
        'itemsPerPage' => 20,
        'storagePid'   => 1,
    ],
];

Write mode 

By default, write operations (create, update, delete) run under the acting-user context — TYPO3's DataHandler preserves the caller's identity for audit purposes. Set writeMode to system_admin to bypass TYPO3 ACL checks entirely. Only use this for trusted, back-channel APIs.

'general' => [
    'table'        => 'tx_myext_domain_model_article',
    'resourceName' => 'articles',
    'resourceType' => 'Article',
    'operations'   => ['create', 'update', 'delete'],
    'writeMode'    => 'system_admin',   // default: 'acting_user'
],

Minimal example (zero-config) 

Three keys are all that is needed for a public read-only resource. operations defaults to ['list', 'show'] and both are PUBLIC by default:

return [
    'general' => [
        'table'        => 'tx_myext_domain_model_article',
        'resourceName' => 'articles',
        'resourceType' => 'Article',
    ],
];

To enable write operations, add them explicitly and configure security:

use MaikSchneider\TcaApi\Enum\AccessRole;

return [
    'general' => [
        'table'        => 'tx_myext_domain_model_article',
        'resourceName' => 'articles',
        'resourceType' => 'Article',
        'operations'   => ['list', 'show', 'create', 'update', 'delete'],
        'storagePid'   => 1,
    ],
    'security' => [
        'create' => AccessRole::FE_USER,
        'update' => AccessRole::FE_USER,
        'delete' => AccessRole::BE_ADMIN,
    ],
];

Full example 

use MaikSchneider\TcaApi\Enum\AccessRole;
use MaikSchneider\TcaApi\Filter\ExactFilter;
use MaikSchneider\TcaApi\Filter\MmFilter;
use MaikSchneider\TcaApi\Serializer\FileProcessing\FileProcessor;
use MaikSchneider\TcaApi\Serializer\Processing\TypoLinkProcessor;

return [
    'general' => [
        'table'        => 'tx_myext_domain_model_article',
        'resourceName' => 'articles',
        'resourceType' => 'Article',
        'operations'   => ['list', 'show', 'create', 'update', 'delete'],
    ],
    'columns' => [
        'title' => [
            'type'       => 'string',
            'groups'     => ['list', 'show', 'create', 'update'],
            'required'   => true,
            'validators' => [
                ['type' => 'maxLength', 'max' => 20],
                ['type' => 'minLength', 'min' => 3],
                ['type' => 'regex', 'pattern' => '/^[\w\s]+$/u'],
            ],
        ],
        'color_id'   => ['groups' => ['list', 'show', 'create', 'update']],
        'categories' => ['groups' => ['list', 'show', 'create', 'update']],
        'profile_photo' => ['groups' => ['list', 'show']],
        'downloads' => [
            'groups'    => ['list', 'show'],
            'processor' => FileProcessor::class,
        ],
        'article_url' => [
            'groups'    => ['list', 'show'],
            'processor' => TypoLinkProcessor::class,
        ],
    ],
    'filters' => [
        'title'      => ExactFilter::class,
        'color_id'   => ExactFilter::class,
        'categories' => MmFilter::class,
    ],
    'order' => [
        'allowed' => ['title', 'uid'],
        'default' => ['uid' => 'asc'],
    ],
    'security' => [
        'list'   => AccessRole::PUBLIC,
        'show'   => AccessRole::PUBLIC,
        'create' => AccessRole::FE_USER,
        'update' => AccessRole::FE_USER,
        'delete' => AccessRole::BE_ADMIN,
    ],
];

How it works 

At boot time the loader runs two passes over every active package:

1. Base pass — loads every Configuration/TcaApi/*.php file and writes the result into $GLOBALS['TCA_API'] keyed by resourceName. When two packages define the same resourceName, the last package to load wins (TYPO3 package load order).
2. Override pass — requires every Configuration/TcaApi/Overrides/*.php file (depth 0, sorted alphabetically within each package). Override files are plain PHP side-effects on $GLOBALS['TCA_API'] — no return value is expected.

After both passes the global is parsed into typed ApiDefinition DTOs and cached. At runtime, use ApiRegistry::get() to read definitions; the global itself is not guaranteed to be set on cache hits.

Writing an override file 

Create a PHP file under Configuration/TcaApi/Overrides/ in any active extension. The filename is arbitrary.

Add a column

<?php

declare(strict_types=1);

// EXT:my_ext/Configuration/TcaApi/Overrides/ExtendArticles.php
$GLOBALS['TCA_API']['articles']['columns']['subtitle'] = [
    'groups' => ['list', 'show'],
];

Remove a column

unset($GLOBALS['TCA_API']['articles']['columns']['internal_notes']);

Restrict operations

$GLOBALS['TCA_API']['articles']['general']['operations'] = ['list', 'show'];

Change a security role

use MaikSchneider\TcaApi\Enum\AccessRole;

$GLOBALS['TCA_API']['articles']['security']['delete'] = AccessRole::FE_USER;

Add a filter

use MaikSchneider\TcaApi\Filter\ExactFilter;

$GLOBALS['TCA_API']['articles']['filters']['category_id'] = ExactFilter::class;

Multiple overrides for the same resource are applied in alphabetical filename order within a package, and in TYPO3 package load order across packages. The last write always wins.

Explicit vs. implicit mode 

The visibility mode — implicit (all TCA columns exposed) vs. explicit (only columns with groups) — is re-evaluated after all overrides are applied.

• Adding a column with a groups key to an otherwise implicit resource switches it to explicit mode for that resource.
• Removing the only column that had groups switches it back to implicit.
• Adding a column without groups to an explicit resource keeps it explicit; the new column is recorded in the DTO but excluded from all operation outputs.

Visibility modes 

TCA_API has two visibility modes. The mode is auto-detected per resource:

Default mode

Active when no column has groups set. All non-system TCA columns (i.e. not hidden, deleted, tstamp, crdate, language/workspace fields) are automatically exposed for read and write.

Explicit mode

Active as soon as any column declares groups. Only columns with a matching groups entry are exposed; all others are hidden.

Serialization groups 

Use groups to control visibility per operation:

'columns' => [
    'title'  => ['groups' => ['list', 'show', 'create', 'update']],  // everywhere
    'teaser' => ['groups' => ['list']],                              // list only
    'body'   => ['groups' => ['show']],                              // detail view only
    'secret' => ['groups' => []],                                    // never exposed
],

Valid group names: list, show, create, update.

Column options reference 

All keys are optional.

Field type support 

The serializer automatically handles all TYPO3 TCA field types. Relational types are resolved via dedicated serializers; scalar types that store encoded data are decoded before output; sensitive types are excluded entirely.

An explicit processor on a column definition always overrides the automatic handling described above.

Column processors 

Column processors transform values during serialization. The extension ships two built-in processors:

FileProcessor

Serialises file references (FAL). Useful for file download columns.

use MaikSchneider\TcaApi\Serializer\FileProcessing\FileProcessor;

'downloads' => [
    'groups'    => ['list', 'show'],
    'processor' => FileProcessor::class,
],

Copied!

TypoLinkProcessor

Resolves TYPO3 typolinks to full URLs.

use MaikSchneider\TcaApi\Serializer\Processing\TypoLinkProcessor;

'article_url' => [
    'groups'    => ['list', 'show'],
    'processor' => TypoLinkProcessor::class,
],

Copied!

ImageProcessor

Serialises image file references (FAL) with full crop-variant support and configurable processing options. By default the processor is used for every type=file TCA column that has no explicit processor key.

Options are controlled via the image sub-key on the column definition:

use MaikSchneider\TcaApi\Serializer\FileProcessing\ImageProcessor;

'hero_image' => [
    'groups'    => ['list', 'show'],
    'processor' => ImageProcessor::class,  // optional — also the default for type=file
    'image'     => [
        'maxWidth'      => 1200,
        'maxHeight'     => 800,
        'fileExtension' => 'webp',
        // omit cropVariant → all variants returned as a map
    ],
],

Copied!

Output mode 1 — all variants (cropVariant omitted or null):

Every crop variant stored on the file reference is processed and returned as a cropVariants map:

{
    "hero_image": {
        "publicUrl": "/fileadmin/hero.jpg",
        "mimeType": "image/jpeg",
        "fileSize": 204800,
        "metadata": {
            "title": "Hero",
            "alternative": "A hero image",
            "description": null,
            "copyright": "© 2026"
        },
        "cropVariants": {
            "default": {
                "publicUrl": "/fileadmin/_processed_/hero_c.webp",
                "width": 1024,
                "height": 512
            },
            "mobile": {
                "publicUrl": "/fileadmin/_processed_/hero_m.webp",
                "width": 375,
                "height": 200
            }
        }
    }
}

Copied!

Output mode 2 — single variant (cropVariant set to a variant ID):

Only that variant is processed and the result is inlined as the top-level image — no cropVariants key:

'hero_image' => [
    'groups' => ['list', 'show'],
    'image'  => [
        'maxWidth'    => 1200,
        'cropVariant' => 'default',    // single-variant mode
    ],
],

Copied!

{
    "hero_image": {
        "publicUrl": "/fileadmin/_processed_/hero_c.webp",
        "width": 1200,
        "height": 600,
        "mimeType": "image/jpeg",
        "fileSize": 204800,
        "metadata": { "title": "Hero", "alternative": null, "description": null, "copyright": null }
    }
}

Copied!

Key	Type	Description
width	string	Target width. Accepts a plain integer ("400"), crop-scale ("400c"), or scale-down-only ("400m"). Mutually usable with maxWidth.
height	string	Target height — same notation as width.
minWidth	int	Minimum width in pixels. Must be a positive integer.
minHeight	int	Minimum height in pixels. Must be a positive integer.
maxWidth	int	Maximum width in pixels. Must be a positive integer.
maxHeight	int	Maximum height in pixels. Must be a positive integer.
cropVariant	string	Crop variant identifier (e.g. 'default', 'mobile'). When set, only that variant is processed and the URL is returned as top-level publicUrl (no cropVariants key). When omitted, all variants are returned as a cropVariants map.
fileExtension	string	Target file extension for format conversion, e.g. 'webp'.
absolute	bool	Force an absolute URL. Default: false.

Custom processors must implement \MaikSchneider\TcaApi\Serializer\Processing\ColumnProcessorInterface.

Callable 

A callable receives the already-serialized row and the raw DB record, and returns any serializable value:

'virtualProperties' => [
    'displayName' => [
        'callback' => [DisplayNameCallable::class, 'build'],
        'groups'   => ['list', 'show'],
    ],
],

The callable signature is (array $serializedRow, array $rawRow): mixed. $serializedRow reflects columns already serialized in this request; $rawRow is the raw DB record.

Column processor 

A virtual property can also use a column processor:

'virtualProperties' => [
    'titleUppercase' => [
        'processor' => UppercaseProcessor::class,
        'groups'    => ['list', 'show'],
    ],
],

The processor implements \MaikSchneider\TcaApi\Serializer\Processing\ColumnProcessorInterface. Without a column key the value passed to the processor is null.

Referencing an existing column 

Add a column key to source the virtual property's value from an existing DB column:

'virtualProperties' => [
    'titleCopy' => [
        'column'    => 'title',
        'processor' => MyProcessor::class,
        'groups'    => ['list', 'show'],
    ],
],

The processor receives the column's raw DB value instead of null.

'virtualProperties' => [
    'profile_photo_thumb' => [
        'column'  => 'profile_photo',     // existing type=file column
        'image'   => [
            'maxWidth'    => 200,
            'maxHeight'   => 200,
            'cropVariant' => 'default',   // single variant → flat publicUrl/width/height
        ],
        'groups'  => ['list'],            // small thumb in list only
    ],
    'profile_photo_large' => [
        'column'  => 'profile_photo',
        'image'   => [
            'maxWidth'  => 1600,
            'maxHeight' => 1200,
            // no cropVariant → all variants returned as cropVariants map
        ],
        'groups'  => ['show'],            // full size in show only
    ],
],

Visibility gate 

Virtual properties respect the same serialization groups as regular columns. When any column has a groups key (explicit mode), virtual properties without groups are excluded:

'virtualProperties' => [
    'displayName' => [
        'callback' => [DisplayNameCallable::class, 'build'],
        'groups'   => ['list', 'show'],  // required in explicit mode
    ],
    'adminNote' => [
        'callback' => [AdminNoteCallable::class, 'build'],
        'groups'   => ['show'],          // only in show, not list
    ],
],

Virtual property options reference 

Built-in filter classes 

Configuration examples 

use MaikSchneider\TcaApi\Filter\ExactFilter;
use MaikSchneider\TcaApi\Filter\PartialFilter;
use MaikSchneider\TcaApi\Filter\WordStartFilter;

'filters' => [
    'title'  => ExactFilter::class,            // ?filters[title]=Foo
    'name'   => PartialFilter::class,          // ?filters[name]=oo  → LIKE %oo%
    'slug'   => WordStartFilter::class,        // ?filters[slug]=Fo  → LIKE Fo%
],

use MaikSchneider\TcaApi\Filter\MmFilter;

'filters' => [
    // Shorthand: derive MM config from TCA automatically
    'categories' => MmFilter::class,

    // Options form: supply MM table config explicitly
    'tags' => [
        MmFilter::class,
        [
            'mm_table'       => 'tx_myext_article_tag_mm',
            'mm_local_key'   => 'uid_local',
            'mm_foreign_key' => 'uid_foreign',
        ],
    ],
],

use MaikSchneider\TcaApi\Filter\SearchFilter;

'filters' => [
    'q' => [
        SearchFilter::class,
        [
            'columns' => ['title', 'teaser', 'body'],
            'match'   => 'partial',            // 'partial' (default) or 'word_start'
        ],
    ],
],

use MaikSchneider\TcaApi\Filter\RangeFilter;

'filters' => [
    'year'  => RangeFilter::class,
],

'filters' => [
    'created_at' => [RangeFilter::class, ['type' => 'date']],   // ?filters[created_at][gte]=2024-01-01
    'price'      => [RangeFilter::class, ['type' => 'float']],  // ?filters[price][lte]=99.99
    'sku'        => [RangeFilter::class, ['type' => 'string']], // preserves leading zeros
],

Custom filters 

Implement FilterInterface to create your own filter strategy. The extension discovers all implementations automatically via Symfony DI — no Services.yaml registration is needed.

use MaikSchneider\TcaApi\Filter\FilterContext;
use MaikSchneider\TcaApi\Filter\FilterInterface;
use TYPO3\CMS\Core\Database\Query\QueryBuilder;

final class PublishedAfterFilter implements FilterInterface
{
    public function apply(QueryBuilder $qb, FilterContext $context): void
    {
        $qb->andWhere($qb->expr()->gte(
            $context->column,
            $qb->createNamedParameter((int)$context->value),
        ));
    }
}

FilterContext is a typed readonly value object:

Use $context->option('key', $default) to read from options with a fallback default.

Register it the same way as built-in filters:

'filters' => [
    'myColumn' => MyCustomFilter::class,
    // or with options — accessed via $context->option('key')
    'other'    => [MyCustomFilter::class, ['key' => 'value']],
],

Default values and private filters 

Two meta-keys are available on any filter definition and control server-side defaults and enforcement:

use MaikSchneider\TcaApi\Filter\ExactFilter;

'filters' => [
    // Overrideable default — applied when ?filters[color_id] is absent
    'color_id' => [ExactFilter::class, ['default' => '1']],

    // Private filter — default always applies, cannot be overridden via
    // URL, and does not appear in the OpenAPI spec
    'deleted' => [ExactFilter::class, ['default' => '0', 'private' => true]],
],

A private filter without a default has no effect.

Boot-time pre-resolution (FilterPreResolvableInterface) 

For filters that need expensive configuration — such as TCA schema lookups — implement FilterPreResolvableInterface in addition to FilterInterface:

use MaikSchneider\TcaApi\Filter\FilterContext;
use MaikSchneider\TcaApi\Filter\FilterDefinition;
use MaikSchneider\TcaApi\Filter\FilterInterface;
use MaikSchneider\TcaApi\Filter\FilterPreResolvableInterface;
use TYPO3\CMS\Core\Database\Query\QueryBuilder;

final class MyExpensiveFilter implements FilterInterface, FilterPreResolvableInterface
{
    public function preResolve(FilterDefinition $definition): FilterDefinition
    {
        // Called once at definition build time (cache miss).
        // Derive expensive config and bake it in via withOptions().
        if ($definition->table === '') {
            return $definition; // guard for unit-test contexts
        }
        return $definition->withOptions(['resolved_value' => $this->deriveFromTca($definition)]);
    }

    public function apply(QueryBuilder $qb, FilterContext $context): void
    {
        // $context->option('resolved_value') is already set from preResolve()
        $qb->andWhere($qb->expr()->eq(
            $context->column,
            $qb->createNamedParameter($context->option('resolved_value')),
        ));
    }
}

ApiDefinitionLoader calls preResolve() once per filter column during the definition build (on cache miss). The returned FilterDefinition, with derived options merged in, is stored alongside the ApiDefinition cache entry. Subsequent boots load the pre-resolved definition directly — the TCA lookup does not repeat.

apply() must remain safe when preResolve() was never called (unit-test contexts where no loader is involved). Check $definition->table === '' or $context->option('resolved_value') === null as guards.

Configuration 

'order' => [
    'allowed' => ['title', 'uid'],       // columns allowed for sorting
    'default' => ['uid' => 'asc'],       // fallback when no order is requested
],

Usage 

Sorting is controlled via the order query parameter:

GET /_api/articles?order[title]=asc
GET /_api/articles?order[uid]=desc

Only columns listed in allowed are accepted. If the client requests an unsupported column, the default order is used instead.

Default access roles 

Operations not listed in security fall back to sensible defaults:

Access roles 

Configuration 

use MaikSchneider\TcaApi\Enum\AccessRole;

'security' => [
    // list and show are PUBLIC by default — only specify to restrict them
    'create' => AccessRole::FE_USER,
    'update' => AccessRole::OWNER,      // Only the record owner may update
    'delete' => AccessRole::OWNER,
],

Callable voters 

For custom access logic, use a callable instead of an AccessRole enum value. The callable receives the PSR-7 server request and an optional record array (for object-level security):

'security' => [
    'create' => [MyAccessChecker::class, 'checkCreatePermission'],
],

The callable must return true to grant access or false to deny it.

class MyAccessChecker
{
    public static function checkCreatePermission(
        \Psr\Http\Message\ServerRequestInterface $request,
        ?array $record = null
    ): bool {
        // Custom access logic
        return true;
    }
}

Ownership 

The ownership section enables declarative record-level security for write operations. It pairs with AccessRole::OWNER in the security config.

use MaikSchneider\TcaApi\Enum\AccessRole;

'security' => [
    'create' => AccessRole::FE_USER,
    'update' => AccessRole::OWNER,
    'delete' => AccessRole::OWNER,
],
'ownership' => [
    'column' => 'fe_user_id',   // DB column holding the owner's FE user UID
],

What this does:

• On create — the fe_user_id column is automatically set to the authenticated FE user's UID server-side. The client cannot supply this value; it is stripped from the request body regardless of the column's groups config.
• On update/delete — the record's fe_user_id is compared to the current FE user's UID. If they don't match the request returns 403.

'ownership' => [
    'column'      => 'fe_user_id',      // column checked on update/delete (also written on create)
    'setOnCreate' => 'fe_creator_id',   // additional column written on create only
],

'ownership' => [
    'column'        => 'fe_user_id',
    'beAdminBypass' => false,           // default: true
],

Table write restrictions 

The API enforces a built-in deny list for tables that must never be written through the API regardless of security configuration. Attempting to write to any of these tables returns 403 Forbidden:

• be_users, be_groups, be_sessions
• fe_sessions
• sys_filemounts, sys_be_shortcuts, sys_action, sys_log

This protection is unconditional and cannot be overridden by configuration.

Denied access 

When access is denied, the API returns:

• 401 Unauthorized — when no user is authenticated but one is required.
• 403 Forbidden — when the authenticated user does not have sufficient privileges.

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 

Validator types 

Configuration 

'columns' => [
    'title' => [
        'groups'     => ['list', 'show', 'create', 'update'],
        'required'   => true,
        'validators' => [
            ['type' => 'maxLength', 'max' => 255],
            ['type' => 'minLength', 'min' => 3],
            ['type' => 'regex', 'pattern' => '/^[\w\s]+$/u'],
        ],
    ],
],

Error response 

Validation failures return 422 Unprocessable Entity with a Hydra-compatible error response:

{
    "@context": "http://www.w3.org/ns/hydra/context.jsonld",
    "@type": "hydra:Error",
    "hydra:title": "Validation Failed",
    "hydra:description": "1 validation error(s)",
    "violations": [
        {
            "propertyPath": "title",
            "message": "Field 'title' is required.",
            "code": "REQUIRED"
        }
    ]
}

PATCH behaviour 

On PATCH requests (partial updates), the required check is skipped for fields that are not present in the request body. Only the submitted fields are validated.

How it works 

When a column has an upload key defined:

1. The client sends the request as multipart/form-data instead of JSON.
2. The file is validated against the constraints in upload and the allowed extensions from the TCA type=file column config.
3. On success the file is stored in the configured FAL storage folder and a sys_file_reference record is created, linking the file to the parent record.
4. On PATCH requests, existing file references are replaced when a new file is uploaded for that column. If the upload field is omitted entirely, existing references are preserved (PATCH semantics).

Configuration 

Add an upload key to any type=file column:

use MaikSchneider\TcaApi\Serializer\FileProcessing\FileProcessor;

'columns' => [
    'profile_photo' => [
        'groups' => ['list', 'show', 'create', 'update'],
        'upload' => [
            'folder'      => '1:/user_upload/',
            'maxSize'     => '5M',
            'duplication' => 'rename',
        ],
    ],
    'downloads' => [
        'groups'    => ['list', 'show', 'create', 'update'],
        'processor' => FileProcessor::class,
        'upload'    => [
            'folder'  => '1:/user_upload/',
            'maxSize' => '20M',
        ],
    ],
],

Upload config reference 

Allowed file extensions 

Allowed extensions are not configured in the upload key — they are read at validation time from the TCA type=file column's allowed config:

// EXT:myext/Configuration/TCA/tx_myext_domain_model_article.php
'profile_photo' => [
    'config' => [
        'type'    => 'file',
        'allowed' => 'jpg,jpeg,png,gif,webp',
    ],
],

The special value common-image-types is resolved via $GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext'].

When no allowed key is present, all file types are accepted.

Sending a file upload request 

Use Content-Type: multipart/form-data. All non-file fields are sent as regular form parts; file fields are sent as file parts.

curl -X POST https://example.com/_api/articles \
  -H "Cookie: fe_typo_user=..." \
  -F "title=My Article" \
  -F "profile_photo=@/path/to/photo.jpg"

# Replace only the file — title is unchanged
curl -X PATCH https://example.com/_api/articles/1 \
  -H "Cookie: fe_typo_user=..." \
  -F "profile_photo=@/path/to/new-photo.jpg"

# Update only the title — existing file reference is preserved
curl -X PATCH https://example.com/_api/articles/1 \
  -H "Cookie: fe_typo_user=..." \
  -F "title=Updated Title"

curl -X POST https://example.com/_api/articles \
  -F "title=My Article" \
  -F "downloads[]=@/path/to/file1.pdf" \
  -F "downloads[]=@/path/to/file2.pdf"

Validation errors 

Upload violations return 422 Unprocessable Entity in the same structured format as other validation errors:

{
    "@context": "http://www.w3.org/ns/hydra/context.jsonld",
    "@type": "hydra:Error",
    "hydra:title": "Validation Failed",
    "hydra:description": "2 validation error(s)",
    "violations": [
        {
            "propertyPath": "profile_photo",
            "message": "The file type is not allowed.",
            "code": "UPLOAD_MIME_TYPE"
        },
        {
            "propertyPath": "profile_photo",
            "message": "The file exceeds the maximum allowed size.",
            "code": "UPLOAD_MAX_SIZE"
        }
    ]
}

Violation codes 

OpenAPI / Swagger UI 

Upload columns are reflected in the auto-generated OpenAPI spec as binary fields in a multipart/form-data request body. The Swagger UI renders an interactive file-picker for every upload column, so you can test uploads directly from the browser.

Combining uploads with read processors 

A column can have both an upload key and a processor key. The upload key controls how incoming files are stored; the processor controls how the stored file references are serialized in read responses:

use MaikSchneider\TcaApi\Serializer\FileProcessing\FileProcessor;
use MaikSchneider\TcaApi\Serializer\FileProcessing\ImageProcessor;

'columns' => [
    // Accept uploads, serialize as full file metadata on read
    'downloads' => [
        'groups'    => ['list', 'show', 'create', 'update'],
        'processor' => FileProcessor::class,
        'upload'    => ['folder' => '1:/downloads/'],
    ],
    // Accept uploads, serialize with crop-variant data on read
    'hero_image' => [
        'groups'    => ['list', 'show', 'create', 'update'],
        'processor' => ImageProcessor::class,
        'upload'    => ['folder' => '1:/images/', 'maxSize' => '10M'],
    ],
],

Configuration 

Add a cache section to any resource definition:

return [
    'general' => [
        'table'        => 'tx_myext_domain_model_article',
        'resourceName' => 'articles',
        'resourceType' => 'Article',
        'operations'   => ['list', 'show'],
    ],
    'cache' => [
        'enabled'            => true,
        'lifetime'           => 3600,          // seconds; default: 86400
        'parametersToIgnore' => ['preview'],   // bypass cache when ?preview=… present
    ],
];

Cache flow 

For every GET request to a cached resource the dispatcher:

1. Builds a cache key from the operation, resource name, UID, and sorted query parameters.
2. Checks the tca_api TYPO3 cache.
3. HIT — returns the stored response body with X-TCA-API-Cache: HIT header.
4. MISS — runs the handler, serializes records (tagging each one as {table}_{uid}), stores the response, and returns it with X-TCA-API-Cache: MISS and X-Cache-Tags headers.

Cache invalidation 

Cache entries are invalidated automatically via a TYPO3 DataHandler hook (clearCachePostProc) whenever a record is created, updated, or deleted through the TYPO3 backend. All cached responses tagged with the affected table name are flushed.

Cache backend 

The extension registers the tca_api cache with an empty configuration, which defaults to TYPO3's Typo3DatabaseBackend (tables cf_tca_api / cf_tca_api_tags). For production use, configure a faster backend in config/system/settings.php (or LocalConfiguration.php):

$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations']['tca_api'] = [
    'backend'  => \TYPO3\CMS\Core\Cache\Backend\FileBackend::class,
    'frontend' => \TYPO3\CMS\Core\Cache\Frontend\VariableFrontend::class,
    'options'  => ['defaultLifetime' => 86400],
];

A Redis or Memcached backend can further reduce response times for high-traffic deployments.

Behaviour 

• Only GET is allowed — write operations are not supported on userinfo endpoints.
• Returns 403 Forbidden if no FE user is authenticated.
• All column features work as normal: embed, virtualProperties, column processors.
• The security and operations keys are ignored — access is always tied to FE user authentication.

CRUD endpoints 

All resources follow a standard REST pattern:

Response format 

All responses use Hydra JSON-LD (application/ld+json).

{
    "@context": "http://www.w3.org/ns/hydra/context.jsonld",
    "@type": "Article",
    "@id": "/_api/articles/1",
    "uid": 1,
    "title": "Hello World"
}

{
    "@context": "http://www.w3.org/ns/hydra/context.jsonld",
    "@type": "hydra:Collection",
    "hydra:totalItems": 42,
    "hydra:member": [
        {
            "@type": "Article",
            "@id": "/_api/articles/1",
            "uid": 1,
            "title": "Hello World"
        }
    ],
    "hydra:view": {
        "@type": "hydra:PartialCollectionView",
        "hydra:first": "/_api/articles?page=1",
        "hydra:last": "/_api/articles?page=3",
        "hydra:next": "/_api/articles?page=2"
    }
}

Pagination 

Collections support offset-based pagination with Hydra PartialCollectionView links.

GET /_api/articles?page=2
GET /_api/articles?page=2&itemsPerPage=10

The response includes navigation links in the hydra:view object (hydra:first, hydra:last, hydra:next, hydra:previous).

The default page size is controlled by:

1. The resource's itemsPerPage setting (per-resource override).
2. The site setting tca_api.defaultItemsPerPage (global default, 20).

Filtering 

Filter parameters can be passed as plain top-level query parameters:

GET /_api/articles?title=Hello
GET /_api/articles?color_id=1
GET /_api/articles?categories=5

The legacy bracket notation is also accepted:

GET /_api/articles?filters[title]=Hello
GET /_api/articles?filters[price][gte]=10&filters[price][lte]=100

When both styles are present for the same column, the bracket form wins. Only columns declared as filters in the resource configuration are matched; other top-level parameters are ignored.

See Filters for the full list of filter strategies and configuration.

Sorting 

Sorting is controlled via the order query parameter:

GET /_api/articles?order[title]=asc
GET /_api/articles?order[uid]=desc

See Sorting for configuration details.

Sparse fieldsets 

Use the fields parameter to request only specific columns:

GET /_api/articles?fields[]=title&fields[]=uid

Only the requested fields (plus @id, @type, and uid) are included in the response.

OpenAPI spec & Swagger UI 

The extension generates a live OpenAPI 3.0 JSON spec from the registered resources and exposes two additional endpoints:

Access to both endpoints is controlled by the tca_api.openApiExposed and tca_api.swaggerUiEnabled site settings respectively. Both default to PUBLIC.

API Platform Admin 

TCA_API is compatible with API Platform Admin out of the box. The extension emits the Hydra vocabulary that the admin's analyzer expects:

• Entrypoint ({apiPrefix}/) lists all resources as Hydra links.
• API documentation ({apiPrefix}/docs.jsonld) describes supported classes, properties, and operations in Hydra class format.
• Collection responses include a hydra:search block with an IRI template that advertises filter parameters using plain field names (e.g. color_id, title), which the admin's analyzer maps directly to filter controls.
• Relations are serialized as plain IRI strings, which API Platform Admin resolves automatically when navigating to a related record.

Point the admin at the entrypoint URL and it will discover resources, relations, and available filters without further configuration:

import { HydraAdmin } from "@api-platform/admin";

export default () => (
    <HydraAdmin entrypoint="https://example.com/_api/" />
);

File uploads 

Columns configured with an upload key accept files via multipart/form-data on POST, PUT, and PATCH requests. See File Uploads for a complete guide including request examples, the upload config reference, validation error codes, and filename mask placeholders.

Available events 

All events are stoppable — call stopPropagation() to abort further processing.

Event API reference 

Registering a listener 

Register event listeners in your extension's Configuration/Services.yaml:

services:
  My\Extension\EventListener\RestrictArticleDeleteListener:
    tags:
      - name: event.listener
        identifier: 'my-extension/restrict-article-delete'
        event: MaikSchneider\TcaApi\Event\BeforeOperationEvent

Example listener 

The following listener blocks delete requests on a specific table unless a custom request header is present. getConfig() returns an ApiDefinition object — access its properties directly.

namespace My\Extension\EventListener;

use MaikSchneider\TcaApi\Event\BeforeOperationEvent;

final class RestrictArticleDeleteListener
{
    public function __invoke(BeforeOperationEvent $event): void
    {
        if ($event->getConfig()->table !== 'tx_myext_domain_model_article') {
            return;
        }

        if ($event->getOperation() !== 'delete') {
            return;
        }

        if (!$event->getRequest()->hasHeader('X-Admin-Token')) {
            $event->stopPropagation(); // dispatcher returns 403
        }
    }
}

Interface 

namespace MaikSchneider\TcaApi\OperationHandler;

use MaikSchneider\TcaApi\Configuration\ApiDefinition;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

interface OperationHandlerInterface
{
    public function supports(
        ServerRequestInterface $request,
        string $operation,
        ApiDefinition $config
    ): bool;

    public function handle(
        ServerRequestInterface $request,
        ApiDefinition $config
    ): ResponseInterface;

    public function getPriority(): int;
}

• supports() — return true if this handler should process the request.
• handle() — execute the operation and return a PSR-7 response.
• getPriority() — higher values are checked first. Built-in handlers use priority 10.

Writing a custom handler 

namespace My\Extension\OperationHandler;

use MaikSchneider\TcaApi\Configuration\ApiDefinition;
use MaikSchneider\TcaApi\OperationHandler\OperationHandlerInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

final class PublishHandler implements OperationHandlerInterface
{
    public function supports(
        ServerRequestInterface $request,
        string $operation,
        ApiDefinition $config
    ): bool {
        return $operation === 'publish'
            && $config->table === 'tx_myext_domain_model_article';
    }

    public function handle(
        ServerRequestInterface $request,
        ApiDefinition $config
    ): ResponseInterface {
        $uid = (int) $request->getAttribute('tca_api.uid');
        // … publish logic …
    }

    public function getPriority(): int
    {
        return 10;
    }
}

Registering handlers 

No ext_localconf.php changes are needed. TCA_API's Configuration/Services.yaml contains an _instanceof rule that automatically tags every class implementing OperationHandlerInterface with tca_api.operation_handler. The HandlerRegistry collects all tagged services via Symfony's AutowireIterator and sorts them by priority.

All that is required is that the handler class is discoverable by the DI container. If your extension uses the standard service auto-discovery pattern (resource: '../Classes/*'), nothing else is needed. The dispatcher iterates handlers highest priority first and dispatches to the first match.

To override a built-in handler, return a priority higher than 10:

public function getPriority(): int
{
    return 20; // checked before the built-in handler (priority 10)
}

Usage example 

public function handle(
    ServerRequestInterface $request,
    array $config
): ResponseInterface {
    $uid = (int) $request->getAttribute('tca_api.uid');
    $operation = $request->getAttribute('tca_api.operation');
    $filters = $request->getAttribute('tca_api.filters', []);
    $page = $request->getAttribute('tca_api.page', 1);

    // …
}

Request flow 

HTTP Request
    ↓
TcaApiMiddleware (PSR-15 entry point)
    ↓
RequestDispatcher (path parsing, access control, handler dispatch)
    ↓
OperationHandlers (GetCollectionHandler, GetItemHandler, CreateHandler, …)
    ↓
DataRepository (QueryBuilder reads) ↔ DataWriteService (DataHandler writes)
    ↓
ResourceSerializer (DB row → Hydra JSON-LD)
    ↓
HydraResponseBuilder (JSON-LD response assembly)

Key components 

TcaApiMiddleware

PSR-15 middleware that intercepts requests matching the configured API prefix. Checks if the API is enabled for the current site, adds CORS headers if configured, and delegates to RequestDispatcher.

RequestDispatcher

Parses the URL path to determine the resource and operation. Enforces the operation whitelist, checks access control via AccessController, dispatches BeforeOperationEvent, and routes to the matching operation handler via HandlerRegistry.

Operation Handlers

Implement OperationHandlerInterface. Built-in handlers:

• GetCollectionHandler — list operation
• GetItemHandler — show operation
• CreateHandler — POST operation
• UpdateHandler — PUT/PATCH operations
• DeleteHandler — DELETE operation
• GetUserInfoHandler — userinfo operation

DataRepository

Read-only data access via TYPO3 QueryBuilder. Supports filter strategies, sorting, pagination, and PID constraints.

DataWriteService

Wraps TYPO3's DataHandler for create, update, and delete operations. Ensures data integrity and respects TCA rules.

ResourceSerializer

Converts raw database rows to Hydra JSON-LD arrays. Handles column visibility, sparse fieldsets, relation embedding, file processing, and virtual properties.

HydraResponseBuilder

Assembles the final JSON-LD response structure including @context, @type, hydra:member (for collections), hydra:view (pagination), and violations (for validation errors).

ApiRegistry

Static registry that stores all resource configurations. Populated automatically by ApiDefinitionLoader at boot time.

HandlerRegistry

Static registry for operation handlers with priority-based dispatch.

AccessController

Evaluates AccessRole enum values and callable voters against the current request context.

What is shown 

Each resource definition is listed by its resourceName and expanded into all resolved properties. All values reflect the parsed state after ApiDefinitionLoader has normalised the raw PHP arrays — so what you see is exactly what the extension acts on at runtime.

Current state 

TCA_API is in alpha state (version 0.1.0). While the core functionality is stable and tested, the API surface may change between minor releases.

Planned features 

The following features are planned but not yet implemented:

• Custom route patterns — support for custom URL patterns like /user/current (medium priority).
• Inline relation field selection — select specific fields from related records when embedding (high priority).
• Relation filtering in serialization — filter related records during serialization (low priority).

Reporting issues 

Please report bugs and feature requests on the GitHub issue tracker.