API Bundle Overview
This section is for back-end developers. It covers the Symfony side of a CWA site: the bundle, your component entities, users and security, fixtures and caching. For the Vue side, see the Nuxt Module. If you're new to CWA, start with Core Concepts.
The API Components Bundle is the Symfony backend of CWA. It wires together API Platform, Doctrine ORM, LexikJWTAuthenticationBundle and Mercure, and adds the resources a CWA site is built from: layouts, pages, routes, component groups and your own components.
Reading This Section
| Page | What it covers |
|---|---|
| Bundle Setup | Installing the bundle, the files to create, and a first admin user |
| Configuration | Every silverback_api_components option and environment variable |
| Users & Security | Signing in, user emails, and who can read what |
| Components | Your own component entities, their annotations, the built-in Collection and Form components, and component groups and positions |
| Page Data & Nested Pages | Page data, templates, and pages within pages |
| Routes | URLs, redirects, scheduling and the resource manifest |
| Data Fixtures | Seeding a site in code, and capturing one from a database |
| Real-Time Updates | The Mercure hub and the subscriber cookie |
| Versions & Conflicts | Version numbers, If-Match and the 412, and the collaboration state store |
| HTTP Caching | Cache safety, tags, purges and flushes |
| Orphaned Data | Finding and deleting content and files nothing uses |
| Console Commands | Every command, in brief |
| Debugging & Errors | The profiler panel, error status codes and logged failures |
Core Resources
The bundle registers these resources for you. Core resources are served under the /_/ prefix, components under /component/, and page data under /page_data/. These sit below whatever prefix your app mounts API Platform on — /_api in the CWA template, so the full path to layouts is /_api/_/layouts.
| Resource | Endpoint prefix | Purpose |
|---|---|---|
| Layout | /_/layouts | Outer page shell (header/footer) |
| Page | /_/pages | Individual pages with component groups |
| Route | /_/routes | URL → page/page data mapping |
| ComponentGroup | /_/component_groups | Named, ordered lists of components, each belonging to a layout, page or component |
| ComponentPosition | /_/component_positions | Place one component in a group and set its order |
| SiteConfigParameter | /_/site_config_parameters | Key–value site settings |
| CollaborationState | /_/collaboration_states | Admin only. The shared editing state of one field, see Versions & Conflicts › Collaboration States |
| Collection | /component/collections | Proxy to paginated resource lists |
| Form | /component/forms | Symfony form types via API |
Your own components extend AbstractComponent (see Creating Components), and your page data extends AbstractPageData (see Page Data & Nested Pages). Every core resource except SiteConfigParameter and CollaborationState has createdAt and modifiedAt. Components and page data also have a version in _metadata.version; see Versions & Conflicts.
Layout
| Field | Description |
|---|---|
reference | A unique name, such as main |
uiComponent | The Vue layout component that renders it, such as CwaLayoutPrimary |
uiClassNames | Style classes chosen in the admin |
componentGroups | Its component groups |
pages | The pages that use it. Read-only |
search matches reference and uiComponent.
Page
| Field | Description |
|---|---|
reference | A unique name |
layout | The layout it renders in. Required |
isTemplate | Whether page data renders through it. Required |
uiComponent, uiClassNames | The Vue page component, such as CwaPagePrimaryPageTemplate, and its style classes |
title, metaDescription | Used for the page's SEO tags |
route | The route that publishes it, if any |
parentPage, parentPageData | Its parent in a nested hierarchy (see Page Data & Nested Pages › Nested Pages) |
isReachableWithoutRoute | Admin only. See Public Pages Without a Route |
componentGroups | Its component groups |
search matches title, reference and uiComponent, and isTemplate=true or false filters. Page data has the same title, metaDescription, route, parent and isReachableWithoutRoute fields.
Route
A route maps a path to one page or page data record. Its fields, generation, redirects and go-live dates are covered in Routes.
ComponentGroup
| Field | Description |
|---|---|
reference | A unique name. The fixture builder uses {name}_{owner IRI}, or {name}_{locationReference} for a shared group (see Builder Reference › locationReference — Shared Groups) |
location | The IRI of the layout, page or component the group was declared in |
layouts, pages, components | Its owners. A draft of a published component given as an owner is stored as the published component |
componentPositions | Its positions, in order |
allowedComponents | Collection IRIs of the component types it accepts. null accepts every type except explicit-allow-only ones |
maxComponents | The most components it holds. null, the default, is unlimited. See Limiting How Many Components a Group Holds |
GET and PATCH on /_/component_groups/{id}/order read and set the order of its positions in one request. See Reordering a group in one request.
To move a component between positions and page data properties in one request, see Component Groups & Positions › Moving a Component. To list where a component is used, see Component Groups & Positions › Where a Component Is Used.
ComponentPosition
| Field | Description |
|---|---|
componentGroup | The group it belongs to |
component | The component it shows. It can't be a component whose subtree holds the group; see A Component Can't Contain Itself. Written with a draft of a published component, it stores the published component; see Publishable › A Reference to a Draft Stores the Published Component. Absent for a caller who can't see drafts when the component isn't published yet; see Positions Holding an Unpublished Component |
sortValue | Its order in the group, lowest first. Read-only: the server chooses it |
after, before | Write-only. The IRI of a position in the same group to place this one after or before. See Placing a position |
pageDataClass, pageDataProperty | Set together to show the component held in a page data property instead. Admin only on read. See Component Positions from PageData |
SiteConfigParameter
A key (the identifier, such as siteName) and a JSON value. GET /_/site_config_parameters is public and returns up to 100 parameters, so the front end can read the site's settings. Reading one parameter by its key, and every write, needs publishable.permission. A write also purges every cached page; see Purging Every Rendered Page. The Nuxt module's admin edits them as site settings. A deploy can switch maintenance mode (maintenanceModeEnabled) with the Console Commands › maintenance command.
Length Limits
The bundle's text fields are VARCHAR(255) columns. A longer value is a 422, with a violation on the field, before anything is written. These fields have the limit:
| Resource | Fields |
|---|---|
| Layout, Page, component | uiComponent. A page's is measured with the CwaPage prefix the API adds |
| Layout, Page, ComponentGroup | reference |
| Page, page data | title, metaDescription |
| ComponentGroup | location |
| ComponentPosition | pageDataProperty, pageDataClass |
| Route | path, name |
| SiteConfigParameter | key |
| Form | formType |
| Collection | resourceIri |
| User | username, emailAddress, newEmailAddress |
Editors are most likely to meet it on a page's metaDescription.
string columns need the same care: see String Columns Need a Length Limit.