API Usage 

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.

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:

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

OpenAPI spec & Swagger UI 

The extension generates a live OpenAPI 3.1.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/" />
);

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

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.