An API in a B2B gaming platform is not a private interface between two teams who share a standup. It is a contract with dozens of external partners, some of whom will not deploy an update for eighteen months, some of whom have customised their integration in ways their own documentation does not record, and all of whom will be affected by a breaking change at the worst possible moment. Releasing API 3.0 is therefore not a technical milestone; it is a coordinated commercial event. The platforms that handle it well are not the ones with the most elegant new schema—they are the ones with the most disciplined backward compatibility policy and the least ambiguous communication. Continuing the sequence from our analysis of WebGPU 2.0 mobile performance and AI personalization and player LTV, this piece addresses the interface layer those systems are exposed through. Start with the platform overview at DYG Games if you are new to the stack.

What “Breaking” Actually Means in a Partner API

Engineering teams routinely underestimate what constitutes a breaking change, because they evaluate it from the producer’s perspective. The useful definition is consumer-side: a change is breaking if a correctly written consumer could observe different behaviour without any code change on its side. By that definition, the following all break.

• Removing a field — even one the provider believes is unused. It is unused until the day a partner’s reconciliation job reads it.
• Renaming a field — semantically identical to removal plus addition, but harder to detect in a payload diff.
• Tightening a type — accepting an integer where a string was previously accepted is breaking for consumers that stringified it.
• Adding a required field — a request that previously validated now fails.
• Changing an error code or its semantics — consumers branch on error codes; reusing a code for a different condition silently reroutes their retry logic.
• Changing default behaviour — an omitted parameter that previously defaulted to “all” now defaulting to “none” alters results with no schema change at all.
• Altering pagination, ordering, or rate-limit headers — these are part of the contract whether or not they appear in a schema.

The corollary is that the only safe additive change is a nullable optional field with a documented absence semantic. Everything else requires a version boundary. Teams that internalise this stop arguing about whether a change is “technically breaking” and start asking which version it ships in.

The Versioning Policy: What Each Increment May Change

Semantic versioning is widely cited and rarely obeyed. The reason is that most policies stop at the label and never define the change envelope. The table below is the operative policy DYG publishes to integration partners; the right column is what makes it enforceable.

Increment	Permitted Changes	Prohibited	Partner Action Required
PATCH (3.0.x)	Bug fixes, internal performance work, documentation corrections	Any observable change to request or response semantics	None; transparent by definition
MINOR (3.x)	New optional fields, new endpoints, new enum values where the consumer contract permits extension	New required fields, removal, renaming, tightened validation	Adopt at leisure; recommended within two release cycles
MAJOR (4.0)	Any structural change: field removal, rename, auth model change, error-taxonomy revision	Silent coexistence without an announced lifecycle and migration guide	Planned migration within the published deprecation window
Deprecation	Announcement, sunset headers, usage telemetry reporting	Deactivation before the window closes or without usage evidence	Plan, schedule, and confirm cutover

Two rows in that table do the real work. The MAJOR row forbids silent coexistence—a new major version without an announced lifecycle is not a version, it is an outage waiting for a date. The Deprecation row forbids deactivation on a calendar date without usage evidence; a version may only be retired when telemetry shows actual consumption has fallen to an agreed threshold, or when the window has expired and the remaining consumers have been individually notified.

Prefer Expansion Over New Majors

A versioned API’s best outcome is not a successful 3.0 migration—it is a 3.0 that most partners can adopt without touching their code. Every major version carries a coordination cost across the partner estate, and that cost should be paid only when the change genuinely cannot be expressed additively.

Three techniques that avoid unnecessary majors

1. Additive field expansion. Introduce the new representation alongside the old, populate both for a transition period, and document a preference order. Consumers migrate by convenience, not by force.
2. Versioned request semantics over a stable transport. Where behaviour must change, accept an explicit api_version or media-type parameter, allowing a single endpoint to serve two contracts during the transition.
3. Capability negotiation. Publish a capabilities endpoint describing what the caller’s credential is entitled to. Consumers that understand the capability get the new behaviour; those that do not receive the legacy path automatically.

Capability negotiation is the technique most often skipped and most often decisive, because it lets a provider roll out new semantics progressively across a partner estate without a hard version boundary at all. The trade-off is that the provider must maintain two code paths for a defined period, which is precisely the cost that a written deprecation policy is designed to bound.

Deprecation Policy: Turning Windows Into Commitments

A deprecation policy is only credible if it is measurable. The model below is the one DYG publishes; the durations are industry-typical ranges and should be negotiated per relationship rather than assumed.

Stage	Provider Obligation	Partner Obligation
T-12 months — Announcement	Publish migration guide, publish versioning policy, open sandbox	Register interest, schedule internal work
T-6 months — Telemetry	Send per-partner usage reports showing traffic on the retiring version	Begin migration or provide a remediation plan
T-3 months — Sunset headers	Return deprecation and sunset headers on every legacy call	Complete migration; monitor for header warnings
T-0 — Deactivation	Deactivate only after usage evidence confirms the threshold is met	None, if migration completed on schedule

The sunset header mechanism deserves emphasis because it is the only stage that reaches engineers who did not read the announcement email. A response header naming the sunset date appears in the logs of every consumer that ignores it, which converts an organisational communication problem into a technical signal that lands on the right desk.

Never deactivate on a calendar alone

The most damaging pattern in B2B API management is the announced date that is honoured regardless of reality. A partner fails to migrate, the deadline passes, the endpoint is switched off, and the resulting incident damages a commercial relationship far more than the six-month extension would have cost. The correct gate is dual: the window has closed and residual usage is below threshold or the remaining consumers have been individually notified with written acknowledgement.

Contract Testing: Making Compatibility a Build Gate

Contract testing is what converts a versioning policy from a document into an enforced property. The mechanism is straightforward: the consumer’s expectations are captured as executable assertions, and the provider’s build fails if those assertions regress.

The contract test layers

• Schema contracts — structural assertions on request and response shapes, including required fields, types, and nullability.
• Behavioural contracts — assertions on semantics: idempotency under duplicate submission, error codes for defined failure classes, pagination ordering guarantees.
• Economic contracts — assertions that a well-formed round produces a ledger entry reconcilable to the wallet, which is where API correctness becomes financial correctness.
• Negative contracts — assertions on what must not happen: no undocumented error codes, no silent default changes, no unbounded response growth.

Two implementation rules make this work in practice. First, contracts live in the provider’s repository and run on every candidate build, not in a separate QA environment that drifts. Second, the negative contracts—the assertions about prohibited behaviour—are the ones that catch unintended breaking changes in CI, because the additive changes that were intended are already covered by schema tests.

Case Pattern: Migrating a Mixed Partner Estate to API 3.0

The following pattern is a composite drawn from DYG partner migrations and illustrates the sequence rather than reporting a specific partner’s metrics.

Context. A provider operates API 2.x with a mixed estate: a handful of large aggregators on customised integrations, a long tail of operators on standard connectors, and a few partners whose integration predates the current documentation entirely. Version 3.0 introduces a revised error taxonomy, a new authentication model, and field renames in the settlement payload.

Phase one — additive shim. Rather than splitting the estate on day one, the provider introduces the 3.0 payload shape alongside 2.x fields, populated from the same internal model. Consumers see both representations and are invited to adopt the new fields at will. The revised error taxonomy ships as new codes layered on top of legacy codes, with a documented mapping.

Phase two — telemetry-driven segmentation. Capability negotiation identifies which partners can consume the new semantics. Aggregators, whose release cycles are longest, are onboarded first and receive a dedicated migration channel; the long tail migrates through the standard connector, which is updated once on the provider side.

Phase three — contract gate. Before any partner is switched to 3.0, the economic contract suite runs against their integration in the sandbox, asserting that round outcomes reconcile to wallet movements. Partners who pass are cut over; partners who fail receive a discrepancy report rather than a deadline reminder.

Phase four — evidence-based sunset. Legacy field population continues until telemetry shows residual consumption below the agreed threshold. Only then is the 2.x path retired, and the retirement is announced to the specific remaining consumers individually.

What went wrong in weaker attempts. When this sequence is compressed, three failures recur. Consumers are told a date instead of shown a usage report, so they cannot prioritise. The revised error taxonomy is deployed silently, so retry logic misbehaves in ways that surface as duplicate transactions. And the economic contract suite is skipped, so a reconciliation discrepancy discovered weeks later is attributed to the partner, damaging trust at exactly the moment the new version needs advocacy.

Transferable lesson. A major version migration is a change-management programme with an engineering core, not an engineering project with a communications appendix. The parts that determine success—segmentation, telemetry, contract gates, individual notification—are the parts that are not code.

Frequently Asked Questions

Do we need a new major version for a field rename?

Strictly, a rename is a removal plus an addition and is therefore breaking. In practice the lowest-cost resolution is additive: publish the new field name, continue populating the old one, mark the old one deprecated with a documented sunset, and retire it on evidence. A major version is warranted only when the old name must disappear immediately for structural reasons.

How long should a deprecation window be?

Industry-typical windows for a B2B gaming platform run from six to twelve months for standard integrations, and longer for large aggregators whose own release calendars are constrained. The window should be negotiated at contract signature rather than announced at deprecation time, because a window the partner agreed to is a commitment and a window that was announced is a notification.

What is the difference between contract testing and integration testing?

Integration testing verifies that two implementations work together in an environment. Contract testing verifies that the consumer’s expectations remain satisfied by the provider’s current interface, and can run in the provider’s CI pipeline without standing up the consumer at all. The latter is what prevents regressions from reaching partners; the former is what confirms a cutover.

How do we version an API when partners have customised their integration?

Treat customisation as an unregistered contract and discover it with telemetry. The capabilities endpoint and per-partner usage reports reveal which fields and endpoints are actually consumed, which is the only reliable evidence of a customisation’s footprint. Where a partner reports an undisclosed dependency, it is recorded and honoured for the remaining window rather than dismissed as out-of-contract behaviour.

Should version numbers appear in the URL path or in headers?

Both patterns are workable. Path versioning is more visible and easier to route, which suits public documentation and partner onboarding; header or media-type negotiation allows finer-grained transitions on a single endpoint, which suits progressive rollout. Many mature platforms use path versioning for the major boundary and capability negotiation within it—an approach consistent with the distributed architecture patterns DYG publishes.

What telemetry is essential for managing deprecation?

At minimum: request volume per version per partner, distinct endpoints per partner per version, error-rate distribution per version, and first-seen and last-seen timestamps per field. First-seen and last-seen per field are the most valuable and the most commonly omitted—they are what allow a provider to say with confidence that a field is genuinely unused.

How does API versioning interact with the settlement and wallet layers?

Economic contracts bind them together. A version change that alters settlement timing or error semantics must be reflected in the reconciliation rules, or break categories will silently misclassify. This is why the version policy and the reconciliation model should be maintained by the same architecture group—an approach described in our analysis of stablecoin settlement architecture.

Conclusion: A Version Policy Is a Trust Instrument

Partners do not evaluate an API by its schema; they evaluate it by how predictable its operator is. A published igaming API versioning policy with a defined change envelope, a measurable API deprecation policy, enforced contract testing, and evidence-based sunsets sends a single message: this provider will not surprise you. That message is worth more than any individual feature in API 3.0, because it is the reason a platform team is willing to build against the interface in the first place.

Ship majors rarely. Express what you can additively. Make the window a commitment. Gate compatibility in the build. Notify individually before you switch anything off. Do those four things and a 3.0 release becomes what it should be—an upgrade your partners plan for, not an incident they respond to.

DYG publishes its versioning policy, migration guides, and contract-test suites as standard artefacts of every OEM integration, so partner engineers can verify compatibility before a single production call is made. To review the policy against your own estate or plan a migration alongside the wider platform roadmap, contact the DYG integration team or start at dyg-games.com.