I85PREP
⌘ K
Boomi API Management study materials
Boomi API Management study resources

Versioning a Breaking Change Under Governance Review

Boomi API Management · Put your knowledge to work in context.

All case studies

Versioning a Breaking Change Under Governance Review

A fintech's Payments API is consumed by 34 internal services and 6 external partners. The team must change the amount field from a decimal number to a string to support currency-precise values, and remove the deprecated legacyRef field. Governance policy requires: no breaking change without a published deprecation window; all API products must carry an owner and lifecycle stage; and external consumers must be notified through the developer portal. The team wants to ship in 3 weeks because a regulatory deadline is 10 weeks out. Two partners have hard-coded amount as numeric and cannot change before 8 weeks. No automated contract tests exist today.

1. Propose a versioning and rollout strategy that satisfies governance and the regulatory deadline. Justify the sequencing.

Read the worked answer

Ship a new major version (for example v2) rather than mutating v1 in place, because changing amount from number to string and removing legacyRef are both breaking. Sequence:

  1. Weeks 0–1: Register v2 as a distinct API product with owner, lifecycle stage (beta), and portal documentation; mark v1 as deprecated with a published sunset date. This satisfies the governance requirements before any traffic moves.
  2. Weeks 1–3: Publish v2 and run it in parallel with v1. Internal services migrate first (they are under the team's control). Do not remove legacyRef from v1 during this window; keep v1 behavior frozen.
  3. Weeks 3–8: External partners migrate on their own schedule. The two partners needing 8 weeks set the floor for v1 retirement - which is why the regulatory deadline must be met by v2, not by forcing v1 changes.
  4. Week 8+: After confirming zero v1 traffic (or after the sunset date), retire v1 and remove legacyRef.

The regulatory deadline is met because v2 carries the compliant behavior and can go live in 3 weeks; v1 remains a compatibility shim. Forcing the breaking change into v1 would violate governance and break partners.

2. The team argues contract tests are unnecessary because the deprecation window protects consumers. Assess this and describe a minimal test approach.

Read the worked answer

The argument is unsound. A deprecation window is a communication control, not a correctness control: it tells consumers when change arrives but does nothing to detect whether a deployed change actually breaks a consumer's expectations. With 34 internal services and 6 partners, silent breakage (for example a service that parses amount numerically) surfaces in production, after the window, when rollback is expensive. Governance intent - protecting consumers - is only met if you can prove compatibility.

Minimal approach:

  • Schema/contract validation in CI: validate the OpenAPI definition against the published contract on every build; fail the pipeline on breaking diffs (type changes, removed fields).
  • Consumer-driven contract tests for the highest-risk consumers: at minimum the two numeric-amount partners and the internal services that touch payments. Record their expectations against v1 and replay against v2.
  • Canary/shadow traffic: route a small percentage of v2 calls and compare responses against v1 for the same inputs.
  • Traffic-based retirement gate: block v1 sunset until analytics show zero v1 calls for a defined period.

This is proportionate: it targets the fields actually changing rather than building a full test suite.