A2UI Atomic Catalog — API Versioning & Deprecation Policy

Developer & Agent Documentation

Versioning and deprecation policy for developers and AI agents integrating with the A2UI Atomic Catalog.

Wire-Format Versioning (X-API-Version)

Every JSON response carries the wire-format version in an X-API-Version: 1 header rather than an ephemeral URL path prefix. MCP client configurations remain stable and do not require URL migration on minor updates.

Deprecation & Sunset Policy

Breaking changes are announced in advance via standard IETF headers:

• Deprecation (RFC 9745) — timestamp when deprecation takes effect
• Sunset (RFC 8594) — timestamp when deprecated behavior is permanently removed (minimum 90 days notice)

CI Compatibility Parity Gate

Every MCP server and API build runs structural parity tests in CI to verify that existing response shapes remain identical and non-breaking.

Developer Resources

• Versioning Policy (Markdown) — full policy documentation
• OpenAPI 3.1 Specification — machine-readable contract
• API Documentation — REST endpoints and error contracts
• MCP Server Endpoint — JSON-RPC 2.0 integration surface
• Developers Portal — guide to tools and self-hosting