API Usage

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

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

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

Single item response

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

Collection response

{
    "@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:

The resource's itemsPerPage setting (per-resource override).
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:

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.

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.