Versioning and deprecations

Versioned public surfaces

Stable identifiers and dynamic contracts

Use the documented versioned base paths, operation keys, scope IDs, JSON-RPC methods, and MCP tool names as integration identifiers. Display names, descriptions, operation availability, service eligibility, risk policy, input schemas, and returned fields may evolve as Lead360 reviews product behavior and security.

Fetch the current operation contract before execution and reject an unexpected risk tier, effect category, execution mode, required field, or additional property rule. This lets the client fail safely when a contract changes instead of sending an old body into a new workflow.

Backward-compatible client design

• Ignore unknown response fields unless the client policy requires review.
• Do not treat a display label as an operation key.
• Validate required response fields while allowing documented additive metadata.
• Refresh discovery after token, scope, service, registry, or version changes.
• Treat removed access as final until the current public documentation says otherwise.
• Pin and test client dependencies that implement JSON-RPC and MCP behavior.
• Keep a controlled test sub-account and non-sensitive fixtures for upgrades.

Deprecation response

1. Identify every client, token, workflow, and owner using the affected contract.
2. Read the replacement scope, operation, endpoint, or protocol guidance.
3. Update validation and tests before changing production traffic.
4. Create or rotate credentials when the replacement needs a different scope set.
5. Run controlled discovery and read tests in the destination sub-account.
6. Deploy gradually and monitor errors, rate use, and data differences.
7. Remove deprecated logic and revoke obsolete credentials.

Maintain a release testing matrix

For each supported client version, record the REST or MCP surface, token scopes, operation keys, required arguments, expected execution modes, and representative success and failure cases. Include authentication failure, insufficient scope, operation removal, invalid schema, rate limiting, approval required, and temporary adapter failure.

Run the matrix against a controlled non-sensitive sub-account before a client, dependency, protocol, or registry upgrade reaches production. Compare structured fields instead of complete fixture text so harmless wording changes do not hide meaningful contract changes. Require review when an operation moves between direct_read and approval_required or changes risk.

Keep a rollback build and the previous approved configuration until the new release is stable. After rollout, remove unsupported versions, retire temporary credentials, and update the integration owner record and internal runbook.

Schedule a periodic compatibility run even when no release is planned. It can detect expired credentials, changed service entitlements, stale fixtures, dependency drift, and assumptions that no longer match the current production operation contract.