Files
typo3-13/docs/cms-api.md
T
frommeandClaude Opus 5.5 48f22a7787 fix: n8n's JSON-LD endpoint only overwrites plain html content elements
PUT /api/json-ld/{uid} replaced the bodytext of any content element, so a
wrong uid in n8n could wipe visible page content (text, plugins, ...).
Elements of any other CType than html are now refused with 409 before
anything is written.

The group's "Explicitly allow tt_content:CType:html" does not guard this on
its own, since the endpoint bypasses DataHandler's record access checks.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-11-03 09:22:39 +01:00

6.1 KiB

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.
{
  "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.
{
  "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.

  • 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.
[
  {"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).

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.