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 an /api/v1/ prefix (for example /api/v1/subscriptions/...), others carry only /v1/ (/v1/services/...), and others β€” including the Payment Link entry point POST /transactions β€” 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) is unversioned today β€” there is no version segment in its 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.

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 on the Changelog.
  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.