API Versioning Strategy

Last updated: 2026-02-16

This document defines versioning behavior for enterprise API consumers.

1. Current versions

• Canonical version: 2026-02-01
• Supported alias: v1

Version discovery endpoint:

• GET /api/version

2. How to request versions

Preferred:

• Header: x-api-version: 2026-02-01

Also supported:

• x-api-version: v1
• Accept: application/vnd.Bounded Health.v1+json
• Accept: application/vnd.Bounded Health+json; version=2026-02-01

3. Runtime behavior

• If version is supported:
  • request proceeds
  • response includes x-api-version
• If version is unsupported:
  • server returns 400
  • error code: UNSUPPORTED_API_VERSION
  • response includes list of supported values

4. Compatibility guarantees

• No breaking changes inside an active version window
• Additive fields are allowed
• New required fields or behavior changes require a new version

5. Client best practices

• Always send x-api-version
• Alert on UNSUPPORTED_API_VERSION responses
• Validate backward compatibility in staging before upgrading pinned versions
• Keep client and OpenAPI snapshot updates in the same release plan

6. Deprecation workflow (recommended)

• Announce deprecation window in integration release notes
• Provide migration notes and schema diffs
• Run dual-version availability window before retirement