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, and the built-in Collection and Form components |
| 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 |
| 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 regions within a layout, page or component |
| ComponentPosition | /_/component_positions | Ordered slot assignments |
| SiteConfigParameter | /_/site_config_parameters | Key–value site settings |
| 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 has createdAt and modifiedAt.
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 |
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 |
location | The IRI of the layout, page or component the group was declared in |
layouts, pages, components | Its owners |
componentPositions | Its positions, in order |
allowedComponents | Collection IRIs of the component types it accepts. null accepts every type except explicit-allow-only ones |
ComponentPosition
| Field | Description |
|---|---|
componentGroup | The group it belongs to |
component | The component it shows |
sortValue | Its order in the group, lowest first |
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.
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.On the bundle's main branch after 2.0.0-alpha.17 (#430). Before that, a value over 255 characters was a 500 on PostgreSQL and MySQL.