Skip to main content
Migo Docs

API Versioning

Versioning strategy​

Migo favors additive, backward-compatible evolution over forced version bumps. Most changes ship in place without a new version. Where a version segment exists, it is part of the path.

  • Middleware (migo-api) uses per-service path versioning: some service paths carry a /v1/ segment (for example /v1/subscriptions/...) while others — including the Payment Link entry points POST /transactions and POST /transactions-hook — are served at the root with no version segment. Always use the exact path shown in the Middleware API reference and in this portal's recipes; do not assume a /v1/ prefix is present (or absent) for every route.
  • Wallet Gateway (ali-api-gw-rest) and CMS Backoffice (ali-api-cms-rest) are unversioned today — there is no version segment in their paths. Treat the current contract as the baseline.

Use the API Reference as the source of truth for the live path of every endpoint.

What counts as a breaking change​

Breaking (announced in advance, may introduce a new versioned path):

  • Removing an endpoint
  • Removing a response field
  • Changing the type of a request or response field
  • Adding a new required request field
  • Changing URL patterns or HTTP verbs
  • Tightening validation that previously accepted valid input
  • Changing authentication requirements

Non-breaking (ships in place, no new version):

  • Adding a new endpoint
  • Adding an optional request field
  • Adding a new response field
  • Adding a new enum value (clients must ignore unknown values — see below)
  • Performance improvements
  • Bug fixes that make the endpoint conform to its documentation

Client expectations​

To consume Migo APIs resiliently:

  1. Ignore unknown response fields. New fields will appear in existing responses.
  2. Ignore unknown enum values. Treat unknown values as "other" rather than failing.
  3. Never rely on undocumented behavior. If it isn't in the OpenAPI spec, it may change without notice.
  4. Subscribe to the Changelog. Breaking announcements appear there 90+ days in advance.

Deprecation policy​

Forward-looking policy

The header-based deprecation signaling described below is the intended policy. The gateways do not currently emit Sunset / Deprecation / x-migo-warning headers or 410 Gone on a sunset date — rely on the Changelog as the authoritative deprecation channel until this is implemented.

When an endpoint or field is deprecated, the planned signaling is:

  1. We announce on the Changelog with a minimum 90-day sunset window (180 days for breaking changes in production).
  2. Deprecated endpoints will return a Sunset: <rfc-1123-date> response header and a Deprecation: true header.
  3. Responses will include an x-migo-warning header with a link to the migration guide.
  4. After the sunset date the endpoint will return 410 Gone.

How a migration would proceed​

If a breaking change ever requires a new versioned path, the intended sequence is:

  1. The new path ships and is documented in the API Reference.
  2. A migration guide is published on the Changelog.
  3. The superseded path is announced as deprecated, with the sunset window above.
  4. The superseded path is retired only after that window closes.

Complete your migration within the announced window. Support is available via support@migopayments.com.