---
title: "API Usage"
manual: "TCA_API"
version: "2.2"
permalink: "https://docs.typo3.org/permalink/maikschneider/tca-api:api-usage@2.2"
source: "ApiUsage/Index.rst"
rendered: "2026-10-12T13:17:40+00:00"
---

# API Usage {#api-usage}

Once a resource is configured, it is automatically available under the API
prefix (`/_api/` by default).

## CRUD endpoints {#crud-endpoints}

All resources follow a standard REST pattern:

| Method | Endpoint | Description |
| --- | --- | --- |
| `GET` | `/_api/articles` | List collection. |
| `GET` | `/_api/articles/1` | Show a single item. |
| `POST` | `/_api/articles` | Create a new item. Send a JSON body or `multipart/form-data` for file uploads. |
| `PUT` | `/_api/articles/1` | Full update. All writable fields are expected. Use `multipart/form-data` when uploading files. |
| `PATCH` | `/_api/articles/1` | Partial update. Only submitted fields are updated. Existing file references are preserved when the upload field is omitted. |
| `DELETE` | `/_api/articles/1` | Delete an item. |

## Response format {#response-format}

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

### Single item response {#single-item-response}

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

### Collection response {#collection-response}

```json
{
    "@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 {#pagination}

Collections support offset-based pagination with Hydra `PartialCollectionView`
links.

```text
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).
1.  The site setting `tca_api.defaultItemsPerPage` (global default, 20).

## Filtering {#filtering}

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

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

The legacy bracket notation is also accepted:

```text
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](https://docs.typo3.org/permalink/maikschneider/tca-api:filters@2.2) for the full list of filter strategies and configuration.

## Sorting {#sorting}

Sorting is controlled via the `order` query parameter:

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

See [Sorting](https://docs.typo3.org/permalink/maikschneider/tca-api:sorting@2.2) for configuration details.

## Sparse fieldsets {#sparse-fieldsets}

Use the `fields` parameter to request only specific columns:

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

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

Virtual properties are addressed by their property name and are subject to the
same filter — a virtual property that is not listed is neither serialized nor
computed, so its processor or callback never runs:

```text
GET /_api/news?fields[]=title&fields[]=url
```

> [!NOTE]
> A virtual property whose callback reads other keys from the serialized row
> sees only the fields that were requested alongside it. Request its
> dependencies explicitly.

## OpenAPI spec & Swagger UI {#openapi-spec-swagger-ui}

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

| Endpoint | Description |
| --- | --- |
| `{apiPrefix}openapi.json` | Machine-readable OpenAPI spec (e.g. `/_api/openapi.json`). |
| `{apiPrefix}swagger-ui` | Interactive Swagger UI (e.g. `/_api/swagger-ui`). |

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

### Backend module (TYPO3 v14+) {#backend-module-typo3-v14}

On TYPO3 v14 the extension registers a **TCA API** module under the
*Integrations* main module (alongside *Reactions* and *Webhooks*) that renders
the Swagger UI directly in the backend. It is available to administrators and is
**always enabled** — independent of the `tca_api.enabled`,
`tca_api.openApiExposed`, and `tca_api.swaggerUiEnabled` site settings that
gate the public frontend endpoints. The specification is built per site; when
more than one site is configured, a site selector is shown in the module's doc
header.

## API Platform Admin {#api-platform-admin}

TCA_API is compatible with
[API Platform Admin](https://api-platform.com/docs/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:

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

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

### Bundled admin site set {#bundled-admin-site-set}

The extension also ships a ready-made admin as a second site set,
`maikschneider/api-platform-admin`. Adding it to a site turns that site's
pages into a React-based API Platform Admin wired to the configured
`tca_api.apiPrefix`:

```yaml
dependencies:
  - maikschneider/tca-api
  - maikschneider/api-platform-admin
```

> [!WARNING]
> This bundled UI is intended for exploring an API during extension
> development, not for production use, and may be removed in a future
> release. It renders on every page of the site it is added to — use a
> dedicated site or a separate TYPO3 site configuration for it.

## File uploads {#file-uploads}

Columns configured with an `upload` key accept files via
`multipart/form-data` on `POST`, `PUT`, and `PATCH` requests. See
[File Uploads](https://docs.typo3.org/permalink/maikschneider/tca-api:file-uploads@2.2) for a complete guide including request examples, the
`upload` config reference, validation error codes, and filename mask
placeholders.