Versioning & Compatibility

This page defines how g3nretailstack versions its public contracts and how compatibility is managed. Where policy is still evolving, it is marked UNCONFIRMED with a target posture.

API versioning (current)

• No URI versioning (no /v1 prefixes). APIs evolve additively.
• Breaking changes are not permitted on published routes; if required, a new route or new service surface will be introduced.
• OpenAPI and JSON Schemas are published per build for each service (see /common/schemas.html).

X-API-Version response header

Every API response includes a date-based version header:

X-API-Version: 2026-03-04

The value is a calendar date (YYYY-MM-DD) representing the current API contract version. It is set globally and updated whenever a new contract-level release occurs. All 20 services emit this header on every response.

How to use it:

• Log it alongside build_id for support/debugging.
• Assert on it in integration tests to detect unexpected version drift.
• Pin to it if your client needs a stable reference point for the contract surface.

Future version negotiation (not yet active)

The following headers are reserved for future use and are not currently sent or parsed:

Header	Direction	Purpose
Accept-Version	Request	Client requests a specific API version (e.g., Accept-Version: 2026-03-04).
Sunset	Response	Signals that the endpoint will be removed after the given date (RFC 8594).
Deprecation	Response	Signals that the endpoint is deprecated as of the given date (draft-ietf-httpapi-deprecation-header).

When version negotiation is activated:

• If Accept-Version names an unsupported version, the server will return 400 with tag unsupported-version.
• Sunset and Deprecation will be added per-route, not globally, with at least 90 days notice.

If you need a stable version pin today, use the X-API-Version header and the OpenAPI snapshot for that build.

Build metadata (support/debugging)

Every response includes build metadata inside stats:

{
  "stats": {
    "build": {
      "build_major": "MONDAY",
      "build_minor": "1765671116",
      "build_id": "MONDAY-1765671116"
    }
  }
}

Use build_id in support tickets, logs, and integration debugging. The docs footer shows the same build ID and build timestamp.

Compatibility guarantees (baseline)

• Additive fields: safe; clients must ignore unknown fields.
• Field removals / renames: not allowed on published surfaces.
• Enum expansion: allowed; clients must treat unknown enums as “other”.
• Behavioral changes: documented in service pages and, when needed, in a “standardization plan / target posture” section.

Deprecation policy (formal)

g3nretailstack follows a formal deprecation policy for all public contract surfaces. See /common/deprecation-policy.html for notice windows, required headers, and schema requirements.

Compatibility notes per surface

Surface	Compatibility approach
API Gateway	Additive changes only; breaking changes require new routes.
Direct Lambda	Operator/CLI surfaces may evolve faster; always check the service’s surfaces.md.
MCP	Mirrors API/Lambda contract; should remain additive.
Schemas	JSON Schema/OpenAPI snapshots are build-specific.