---
title: "Caching"
manual: "TCA_API"
version: "2.2"
permalink: "https://docs.typo3.org/permalink/maikschneider/tca-api:caching@2.2"
source: "Configuration/Caching.rst"
rendered: "2026-10-12T13:17:40+00:00"
---

# Caching {#caching}

TCA_API supports tag-based HTTP response caching for `list` and `show`
operations. When enabled, responses are stored in a TYPO3 cache and served
from there on subsequent identical requests — bypassing the database query and
serialization entirely.

## Configuration {#configuration}

Add a `cache` section to any resource definition:

```php
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
    ],
];
```

| Key | Required | Default | Description |
| --- | --- | --- | --- |
| `enabled` | No | `false` | Enable caching for this resource. |
| `lifetime` | No | `86400` | Cache TTL in seconds. |
| `parametersToIgnore` | No | `[]` | Query parameters that bypass the cache entirely when present in the request (top-level or nested under `filters[…]`). Useful for preview or debug parameters. |

## Cache flow {#cache-flow}

For every `GET` request to a cached resource the dispatcher:

1.  Builds a cache key from the operation, resource name, UID, sorted query
    parameters, and the resolved language id (see [Languages](https://docs.typo3.org/permalink/maikschneider/tca-api:languages@2.2)). Different
    locales never share a cache entry.
1.  Checks the `tca_api` TYPO3 cache.
1.  **HIT** — returns the stored response body with `X-TCA-API-Cache: HIT`
    header.
1.  **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.

### Response headers {#response-headers}

| Header | Value |
| --- | --- |
| `X-TCA-API-Cache` | `HIT` or `MISS` |
| `X-Cache-Tags` | Space-separated list of tags for the records in this response, e.g. `tx_myext_domain_model_article_1 tx_myext_domain_model_article_2` |

## Cache invalidation {#cache-invalidation}

Cache entries are invalidated automatically from two sources, so cached
responses stay in sync no matter how a record changes:

-   **TYPO3 backend edits** — a DataHandler hook (`clearCachePostProc`) flushes
    all cached responses tagged with the affected table name whenever a record is
    created, updated, or deleted through the backend. Clear-cache commands with
    explicit tags (`TCEMAIN.clearCacheCmd = cacheTag:…`) flush those tags too.
-   **API write operations** (`POST`, `PUT`, `PATCH`, `DELETE`) — each
    write dispatches an `AfterWriteEvent` and `WriteCacheInvalidationListener`
    flushes the affected tags: `create` flushes the table tag (`{table}`);
    `update` and `delete` flush both the table tag (`{table}`) and the
    record tag (`{table}_{uid}`). Writing a record via the API and reading it
    back immediately returns the fresh state.

## Cache backend {#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`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/Configuration/Typo3ConfVars/Index.html#file-project-config-system-settings-php) (or `LocalConfiguration.php`):

```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.