n8n is the source of truth for the SEO markup: the element's bodytext is overwritten with the posted object, wrapped in a ld+json script element. Values are escaped with JSON_HEX_TAG so they cannot close the element. The endpoint has its own key (jsonLdApiKey, header only) and writes through DataHandler as the non-admin backend user _n8n, so every change is in the record history and can be undone there, and the page cache is cleared. Until the key and the user exist on prod, every request answers 403/503. Prod setup (group n8n, user _n8n) is in docs/cms-api.md. Co-Authored-By: Claude Opus 5.5 <[email protected]>
126 lines
6.0 KiB
Markdown
126 lines
6.0 KiB
Markdown
# CMS API
|
|
|
|
Endpoints TYPO3 serves to other systems: **MyE&P** (hotel and product content, calendar hotels),
|
|
the **chatbot** (content feed) and **n8n** (JSON-LD of content elements). They are answered by `EP\EpProducts\Middleware\ApiMiddleware`
|
|
before the page resolver, so they do not depend on a page and are never page-cached.
|
|
|
|
The other side of these contracts is documented in MyE&P's `docs/api-consumer-guide.md`
|
|
(`EP/myep`).
|
|
|
|
## Authentication
|
|
|
|
All endpoints except `/api/json-ld/` (see there) need the shared key `cmsApiKey` from the `ep_products` extension configuration
|
|
(Settings → Extension Configuration → ep_products, tab ContentFeed):
|
|
|
|
- header `X-Api-Key: <key>` (preferred, query strings end up in access logs), or
|
|
- query parameter `?key=<key>`.
|
|
|
|
A missing or wrong key answers `403 {"message": "Invalid or missing api key"}`. An empty
|
|
`cmsApiKey` denies every request. MyE&P sends the key as `APP_CMS_API_KEY`; both sides must be
|
|
changed together.
|
|
|
|
## `GET /api/hotel?hotel=<code>`
|
|
|
|
Content of one hotel, for MyE&P's group house pages and booking flow.
|
|
|
|
- `hotel`: the TYPO3 hotel code or one of its matchcode aliases. In MyE&P this is the
|
|
accommodation's **CMS code** (e.g. `DGSGRP`), which can differ from its calendar code.
|
|
- `400` without `hotel`, `404 {"message": "Hotel not found"}` for an unknown code.
|
|
|
|
```json
|
|
{
|
|
"name": "…", "code": "…",
|
|
"description": "…", "features": "…", "room_types": "…",
|
|
"additional_information": "…", "address": "…",
|
|
"images": {"original": [{"url": "…", "alt": "…", "title": "…"}], "resized": […]},
|
|
"icons": […],
|
|
"region": {"name": "…", "latitude": …, "longitude": …, "webcam": "…", "ski_area": "…",
|
|
"ski_area_extended": "…", "description": "…", "news": "…", "length": …,
|
|
"altitude": …, "lifts": …, "images": {…}, "region_maps": [{"url": "…", "alt": "…", "title": "…"}]}
|
|
}
|
|
```
|
|
|
|
## `GET /api/product?product=<code>[&hotel=<code>]`
|
|
|
|
Content of one product, optionally with a hotel.
|
|
|
|
- `product`: the product code. `400` without it, `404 {"message": "Product not found"}` for an
|
|
unknown code.
|
|
- `hotel` (optional): adds `hotel` with the same content as `/api/hotel`.
|
|
|
|
```json
|
|
{
|
|
"product": {"name": "…", "code": "…", "images": {…}},
|
|
"country": {"name": "…"},
|
|
"region": {…},
|
|
"city": {"name": "…"},
|
|
"hotel": {…}
|
|
}
|
|
```
|
|
|
|
## `GET /api/calendar-hotels`
|
|
|
|
The calendar hotel of every visible product: the hotel codes whose availability TYPO3 shows
|
|
(iCal feed, availability calendar, price calendar). MyE&P syncs its contingent snapshot for
|
|
these codes in addition to its accommodations, so hotels offered only in winter, which have no
|
|
accommodation in MyE&P, have availability too. See [calendars.md](calendars.md).
|
|
|
|
- Only products and hotels that are not hidden or deleted; hotels without a code are left out.
|
|
- Sorted by code; products by uid. Names have line breaks collapsed.
|
|
- `season`: `"s"` (summer), `"w"` (winter) or `null`.
|
|
|
|
```json
|
|
[
|
|
{"code": "DKI", "name": "Sportclub Schwendi", "products": [
|
|
{"uid": 155, "name": "Sportclub Schwendi", "season": "w"},
|
|
{"uid": 362, "name": "Gruppenhaus Schwendi", "season": "s"}
|
|
]}
|
|
]
|
|
```
|
|
|
|
Every code in this list should be a **BusPro calendar code**. A group house's content record
|
|
(`…GRP`, `…SO`) set as a product's calendar hotel puts its CMS code in here, which bpn-connect does
|
|
not know (see [calendars.md](calendars.md#the-calendar-hotel-field)).
|
|
|
|
## `GET /api/content/manifest` and `GET /api/content/records?type=<type>&uids=<uids>`
|
|
|
|
The content feed for the chatbot (`EP\EpProducts\ContentFeed\ContentFeedApi`).
|
|
|
|
- `manifest`: everything the feed publishes (pages of the configured sites and records), with a
|
|
modification timestamp per item. Cached for 10 minutes.
|
|
- `records`: up to 100 records of one type per request. `type` is one of `product`, `hotel`,
|
|
`region`, `country`, `city`, `concept`, `news`; `uids` comma-separated. Uids that are no longer
|
|
eligible are left out, not answered with an error (the consumer reads them as deleted).
|
|
- `400` for an unknown type, no uids or more than 100 uids; `404` for other paths.
|
|
- `503` with `Retry-After: 3600` when the feed is switched off (`contentFeedEnabled = 0`, the kill
|
|
switch for when the host is struggling), `503` when `contentFeedSites` is empty. The consumer
|
|
keeps what it has on a 503; nothing is deleted on the chatbot side.
|
|
|
|
Configuration (extension configuration `ep_products`, tab ContentFeed): `contentFeedEnabled`,
|
|
`contentFeedSites`, `contentFeedLanguages`, `contentFeedExcludedPages`,
|
|
`contentFeedNewsDetailPages`.
|
|
|
|
## `PUT /api/json-ld/<uid>`
|
|
|
|
n8n writes the JSON-LD (SEO markup) of a content element (`EP\EpProducts\JsonLd\JsonLdApi`).
|
|
n8n is the source of truth: the element's `bodytext` is replaced with the posted object wrapped in
|
|
`<script type="application/ld+json">`, whatever the element held before. Other fields (CType,
|
|
hidden, …) are left alone; each translation is its own uid.
|
|
|
|
- Key: `jsonLdApiKey` (extension configuration `ep_products`, tab JsonLd), only as header
|
|
`X-Api-Key`; `?key=` is not accepted.
|
|
- `POST` does the same as `PUT` (n8n's default method).
|
|
- Body: the JSON-LD object (or array of objects) itself, e.g.
|
|
`{"@context": "https://schema.org", "@type": "Event", …}`. Pretty-printed when stored;
|
|
`<` and `>` are escaped as `\u003C`/`\u003E`, so a value cannot close the script element.
|
|
- `200 {"uid": 13169, "pid": 24, "changed": true}`; `changed: false` when the stored markup is
|
|
already identical (nothing written).
|
|
- `400` for invalid JSON or a scalar, `403` for a wrong or missing key, `404` for an unknown or
|
|
deleted uid, `405` for other methods, `503` when the backend user `_n8n` is missing, `500` with
|
|
`errors` when DataHandler refuses the write.
|
|
|
|
The write goes through DataHandler as the backend user `_n8n` (no password, so no login; group
|
|
`n8n` with *Tables (modify)* `tt_content` and *Explicitly allow* `tt_content:CType:html`; page
|
|
permissions are bypassed). Every change is in the element's history, where it can be undone, and
|
|
clears the page cache.
|