Versioning

​

Overview

The Boomerang Developer API is versioned to provide predictable behaviour for production workloads while allowing the platform to evolve safely over time. This page covers:

• How versions are expressed
• What is considered a breaking change
• Stability guarantees for each major version
• Deprecation and end-of-life behaviour

All version-related changes are announced in the Release Notes.

---

​

Version scheme

The API is versioned in the URL path:

• Gateway base: https://gateway.bmrg.app/
• Current major version: /v1/

Versioning is:

• Per API, not per module: all endpoints under /v1/ form one coherent versioned surface.
• Integer-based: future major versions will follow the same pattern (/v2/, /v3/, and so on).
• Explicit: a valid request must target a specific version path.

There is no implicit default version without /vN/.

---

​

Version status

The table below shows the current status of each major version. This table will be updated as new major versions are introduced or existing versions are deprecated or retired.

---

​

Breaking and non-breaking changes

Within a major version (for example, /v1/):

​

Breaking changes

The following are treated as breaking changes and will not be made within a major version:

• Removing an endpoint or changing its URL.
• Removing a response field, or changing its type or meaning.
• Changing required request fields (for example, making an optional field mandatory).
• Changing success HTTP status codes or core error semantics for the same behaviour.
• Changing rate-limit semantics in a way that materially reduces permitted usage for existing well-behaved clients.

If such a change is required, it will be delivered via a new major version (for example, moving from /v1/ to /v2/).

​

Non-breaking changes

The following are treated as backwards-compatible and may occur within a major version:

• Adding new endpoints.
• Adding new optional request parameters with safe defaults.
• Adding new response fields.
• Extending enumerations with additional values, where clients are expected to ignore unknown values.
• Tightening validation where previous behaviour was clearly invalid or undocumented.

Clients should be implemented so that unknown response fields and new enumeration values do not cause failures.

---

​

Stability and support commitments

For each stable major version:

• The version is treated as stable once publicly released.
• Boomerang will not introduce intentional breaking changes within that version, except where required for security, legal, or regulatory reasons.
• When a new major version is released, the previous major version will remain supported for a minimum of 12 months from the announcement of the new version, unless earlier action is required for security or compliance.

During the supported life of a major version:

• Security and reliability fixes may be applied.
• Backwards-compatible enhancements may be added.
• Deprecations are announced before removal.

---

​

Deprecation and end-of-life

When Boomerang intends to remove or materially change part of an existing version, a structured deprecation process is followed.

​

Deprecation of endpoints or fields

For deprecations within a major version:

• Deprecation is announced in the Release Notes.
• Where appropriate, responses from deprecated endpoints may include headers such as:
  • X-Boomerang-Deprecated: true
  • X-Boomerang-Sunset-Timestamp: <unix_epoch_ms>

Unless a shorter period is required for security or legal reasons:

• A minimum of 180 days’ notice will be given between deprecation announcement and removal.

​

End-of-life for a major version

When a major version is scheduled for end-of-life:

1. Announcement
   • The version’s deprecation and planned end-of-life date are announced in the Release Notes.
2. Grace period
   • The version remains operational for at least 12 months after announcement of its replacement, subject to security and compliance constraints.
3. Sunset behaviour
   • Near the end-of-life date, Boomerang may:
     • Return warning headers on responses for that version.
     • Highlight the upcoming removal in documentation and dashboards.
4. Removal
   • After the end-of-life date, requests to the retired version may:
     • Fail with a 4xx error indicating that the version is no longer supported; or
     • In limited, well-defined cases, be served by a newer version where semantics are equivalent.

Exact removal behaviour and timelines will be documented in the Release Notes for the version in question.

---

​

Expectations for clients

To minimise disruption and remain compatible over time, client implementations should:

• Target explicit versions
  Always include the major version in the URL path (for example, /v1/) and avoid assumptions about future versions.
• Handle extensions gracefully
  Ignore unknown fields in responses and design for the possibility of new enumeration values.
• Track deprecations
  Monitor the Release Notes for deprecations and plan migrations within the published windows.
• Plan for migration between major versions
  Treat the announcement of a new major version as the starting point for migration planning from the older version, not as a signal to make immediate, breaking changes on the client side.

This model is intended to provide clear, stable foundations for production use while making future evolution predictable and manageable.