Every hotel field now has one job. The hotel's code and aliases are import codes only (dates, lookups); a new Kalender-Code (calendar_code) decides the availability a record shows and may be shared by a house's summer and winter records. The product's "Unterkunft für Belegungskalender" is replaced by the checkbox "Kalender anzeigen" (show_calendar): a product page shows the calendar of the hotel it displays, the season still decides which one. - Price calendar, price tables, Belegungskalender, iCal feeds and /api/calendar-hotels read the Kalender-Code. A feed without one answers 404 instead of an empty calendar. - The upgrade wizard epProductsCalendarCode fills both fields from calendar_hotel, preserving today's calendars; the deploy runs it between the schema update and the switch. calendar_hotel stays in the database, so the previous release keeps working. ep:calendar-codes lists the product pages whose calendar differs from it. - HotelCodeResolver is the one lookup of import codes (date import, /api/hotel, Travelinfo); a code on several records resolves to the record whose own code it is, then the lowest uid, with a warning. Saving a code that is already another visible record's import code is refused with a message naming that record. - /api/product without hotel attaches the product's only visible Unterkunft (422 otherwise) and adds board_description, additional_services and calendar_hotel_code. Co-Authored-By: Claude Opus 5.5 <[email protected]>
137 lines
6.8 KiB
Markdown
137 lines
6.8 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`: an import code of the record: its "Import-Code" or one of its "Weitere Import-Codes"
|
|
(matchcode aliases), resolved by `HotelCodeResolver`. 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 with a hotel.
|
|
|
|
- `product`: the product code (default language). `400` without it, `404 {"message": "Product
|
|
not found"}` for an unknown code.
|
|
- Without `hotel` (MyE&P's group houses, linked by product code): the product's only visible
|
|
Unterkunft. Any other number of visible Unterkünfte answers `422 {"message": "Product <code>
|
|
links <n> hotels, expected exactly 1", "hotel_count": <n>}`.
|
|
- With `hotel` (MyE&P's booking flow): the record of that import code, as in `/api/hotel`; an
|
|
unknown code gives `"hotel": []`.
|
|
- `board_description`, `additional_services`: raw RTE values, `""` when empty.
|
|
- `calendar_hotel_code`: the Kalender-Code of the hotel when "Kalender anzeigen" is on, else
|
|
`null`. MyE&P compares it with its accommodation's calendar code.
|
|
|
|
```json
|
|
{
|
|
"product": {"name": "…", "code": "…", "images": {…}, "board_description": "…",
|
|
"additional_services": "…", "calendar_hotel_code": "SST"},
|
|
"country": {"name": "…"},
|
|
"region": {…},
|
|
"city": {"name": "…"},
|
|
"hotel": {…}
|
|
}
|
|
```
|
|
|
|
## `GET /api/calendar-hotels`
|
|
|
|
The Kalender-Codes of all visible hotel records: the codes whose availability TYPO3 shows (iCal
|
|
feeds, 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).
|
|
|
|
- One entry per code; `name` of the record whose import code it is, else of the first record.
|
|
- `products`: visible products with "Kalender anzeigen" that link a record with the code under
|
|
Unterkünfte.
|
|
- 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 code** with a contingent (see
|
|
[calendars.md](calendars.md#hotel-codes)).
|
|
|
|
## `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. Only plain html elements
|
|
(`CType` `html`) are written, any other type is refused, so a wrong uid cannot replace visible page
|
|
content. Other fields (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, `409` when the element is not of type `html`, `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.
|