9. Implementation guidance

9.1 Recommended ingestion loop

For your BusinessEntity (HO-XXXXXXXXXXXX), store the last-seen ETag.
On schedule (hourly aligns with max-age=3600; nightly is also acceptable for CMS warm caches), fetch the bulk feed with If-None-Match.
On 304, do nothing — content is unchanged.
On 200, replace the BusinessEntity-level cache with the new @graph contents and persist the new ETag. Each inner QAPage’s identifier is your stable PDP cache key.
On 413, switch to per-entity fetches via the fallbackUrlPattern; aggregate locally.
On 503, treat as transient — back off and retry on the next scheduled tick.
On 429, honor X-RateLimit-Reset as the next eligible request time.

9.2 Parsing & on-page embedding

Use a streaming JSON parser if individual responses can approach the body-byte ceiling (default 10 MB). For a portfolio of a few dozen properties this is not currently a concern.
Tolerate unknown fields — additional optional properties may be added within v3.
The Bonafide identifier on a bare QAPage is stable and is suitable as a cache key. Use it instead of about.name for joins.
When embedding inside a <script type="application/ld+json"> tag, escape </script> sequences inside answer text. Bonafide strips HTML server-side but does not pre-escape JSON-in-HTML sequences.
If you join on propertyId, fetch with ?includePropertyId=true and remember the ETag is flag-specific (see §6.3).
If you want the feature-type grouping on each Question, fetch with ?includeCategory=true and remember the ETag is flag-specific (see §6.4).
To enumerate every property under your brand, call GET /api/v3/content/{brandId}/properties (see §4A) and use each bonafideId as the entityId for per-property fetches. The list is unpaginated and is the full roster, so a listed property may still return 404 on the FAQ feed.

9.3 Observability for support tickets

For incident reports, please include the wall-clock timestamp of the failing request and, when present, the X-Request-Id response header. Server logs are indexed by both fields.