Versioning

The SeatBuilder platform versions its REST surface and its JavaScript SDK independently. Both follow semver and both promise that backwards- compatible additions never bump a major version.

REST API

Every public endpoint lives under the api/v1 global prefix:

POST /api/v1/charts
GET  /api/v1/events/{eventKey}
POST /api/v1/events/{eventKey}/seats/hold
...

Inside v1, the platform only ships additive changes:

• New endpoints, new request fields (always optional), new response fields, new webhook event types.
• Bug fixes that bring runtime behaviour in line with the documented contract.

Any change that would break an existing v1 integration ships at a new prefix — api/v2 — alongside api/v1. Both prefixes run side by side during the deprecation window. There is no auto-upgrade and no implicit prefix rewriting; integrators opt in by changing the URL.

SDK semver

The current SDK version is 4.0.0. It is delivered from the SeatBuilder API's /sdk/ route (an npm package is coming soon). Pin to a version for production:

<script src="https://seatbuilder.org/sdk/v4.0.0/seatbuilder.iife.min.js"></script>

Each major break has been a single, well-scoped surface change:

The v2 semantic change matters: under v1 each event froze the chart layout at event-creation time; under v2 events follow the chart's current published version live. Re-publishing a chart now propagates the new layout to every existing event on next read. Booked-seat consistency across chart changes is the chart owner's responsibility — see Integration for the implications.

v3 makes maxSelectedObjects polymorphic so you can cap selection per pricing category as well as globally. A bare number keeps its v2 meaning (a single total cap), so number-only configs upgrade without a code change; the object form { total?, perCategory? } is additive. See Migrating to 3.0.0 for the full note.

Caching the /sdk/ bundle

The bundle ships from two URLs on the SeatBuilder API, each with a deliberate Cache-Control:

<!-- latest: public, max-age=300 (5 min) — rotates on each release -->
<script src="https://seatbuilder.org/sdk/latest/seatbuilder.iife.min.js"></script>

<!-- versioned: public, max-age=31536000, immutable (1 yr) — never changes -->
<script src="https://seatbuilder.org/sdk/v4.0.0/seatbuilder.iife.min.js"></script>

Which to use. For production, pin to a version (/sdk/v4.0.0/...). Because it is served immutable with a one-year TTL, browsers — and the CDN in front of the API — cache it indefinitely and it can never change under you: a new release publishes a new /sdk/v{X.Y.Z}/ path, it never rewrites an existing one. Use /sdk/latest/ only for quick trials or non-critical embeds — it carries a short 5-minute cache and rotates to the newest bundle on every release, so a deploy can change its behaviour without warning.

Rolling out a new version. When SeatBuilder ships a new SDK release, the /sdk/latest/ URL reflects the new bundle within its 5-minute TTL. To move a pinned integration, change the /sdk/v{X.Y.Z}/ path in your <script> tag to the new version — there is no purge step, because each version has its own immutable URL.

Hardening with Subresource Integrity

Because the versioned URL is immutable, you can add a Subresource Integrity (SRI) hash so the browser refuses a tampered bundle:

<script
  src="https://seatbuilder.org/sdk/v4.0.0/seatbuilder.iife.min.js"
  integrity="sha384-…"
  crossorigin="anonymous"
></script>

Generate the hash from the exact bytes you pin (openssl dgst -sha384 -binary seatbuilder.iife.min.js | openssl base64 -A). The /sdk/ route sends Access-Control-Allow-Origin: *, so crossorigin="anonymous" works from any embedding origin. If you need the SDK build fully under your own CI's release control, serve the same bytes from your own static origin and apply the same SRI hash.