API versioning

Versioning is the mechanism that lets a Generally Available API keep improving while honoring its backward-compatibility promise. When a change breaks code that already uses an endpoint, it ships as a new endpoint version instead of altering the one you use.

Infobip versions its API at two levels:

• Endpoints are versioned individually in the URL path (for example, /sms/3/). This is the version that matters if you call the API directly.
• The OpenAPI document (the machine-readable spec) has its own version, separate from any endpoint. This matters only if you consume the spec programmatically (code generation, spec diffing, automated tooling).

If you integrate directly with the API, read Endpoint versioning and skip the OpenAPI section.

Endpoint versioning

Infobip uses per-endpoint versioning. Unlike APIs that version the entire surface at once, version increments are scoped to a single endpoint. A breaking change to an SMS endpoint does not change the version of WhatsApp endpoints, or of any other endpoint you depend on. This lets you adopt new versions endpoint by endpoint rather than migrating your whole integration at once.

Each endpoint carries its version as an integer in the URL path:

The integer increments only when a breaking change is introduced to that specific endpoint. Non-breaking changes are added in place, without a version increment.

How to find the current version [#how-to-find-the-current-version-endpoint-versioning]

Each endpoint version has its own reference documentation, and the current (recommended) version is marked as such. The version lives in the URL path. An endpoint stays on its version until you move to a later one, so an integration you build does not change under you. When you are ready, adopt a new version by updating the integer in the path (for example, from /sms/2/ to /sms/3/).

Superseded and deprecated versions [#superseded-and-deprecated-versions-endpoint-versioning]

A new endpoint version does not automatically retire the previous one. When Infobip releases a later version of an endpoint, the earlier version usually keeps working and stays supported. Several versions of the same capability can be available at once. A later version can be recommended while the earlier one is superseded. Superseded means that a better option exists and new integrations use it. The earlier endpoint still works, is still supported, and has no sunset date.

Retiring an endpoint is a separate, deliberate step. An endpoint is deprecated (put on a path to retirement) only when there is a specific reason to retire it, such as a newer version replacing it, a third-party provider dropping support, or Infobip no longer offering the feature. Deprecation forces a migration. When Infobip deprecates an endpoint, it notifies you through the deprecation process, and the endpoint keeps working until its sunset date, if it has one.

Breaking and non-breaking changes

Knowing what counts as a breaking change helps you build integrations that stay stable across updates. Infobip keeps breaking changes to a minimum, but in some situations (for example, regulatory changes) one might be unavoidable.

Non-breaking changes are added in place, with no version increment:

• Adding a new optional request parameter
• Adding a new response field
• Adding a new enum value
• Adding a new endpoint
• Deprecating an endpoint (it remains operational until its sunset date)

Breaking changes trigger a new endpoint version:

• Removing a request parameter or response field
• Changing the data type of an existing field
• Changing the meaning or behavior of an existing field
• Making a previously optional parameter required
• Removing or renaming an enum value

Two habits keep an integration stable across these updates. Ignore response fields you do not recognize, and migrate off an endpoint before its sunset date. The Backward compatibility page covers both, with code examples. See Deprecation for how a deprecated version is retired.

OpenAPI document versioning

The OpenAPI document at https://api.infobip.com/platform/1/openapi is versioned independently of individual endpoints, using Semantic Versioning(opens in new tab) (MAJOR.MINOR.PATCH). It describes the current documented behavior of the whole API surface, so its version reflects changes to the document, not to any single endpoint. Product-specific specs (for example, https://api.infobip.com/platform/1/openapi/sms) inherit their version from the main document.

The spec version reflects every change to the document, from documented API behavior to editorial content. A change that does not break clients who followed the deprecation notice is not a breaking (MAJOR) change. The following table describes each increment.

These are the most common examples. Other changes to the documented API behavior or the document structure can also increment the version, depending on their impact. Every release of the OpenAPI document increments the version, including releases that only change descriptions or examples.

The following notes clarify edge cases:

• Deprecated and sunset: Deprecating an endpoint is a MINOR change (it stays in the spec and keeps working). Removing it from the spec after its sunset date is also a MINOR change, because clients that followed the deprecation notice have already migrated.
• Schema renames: A component schema might occasionally be renamed for clarity or consistency. This does not change API behavior, but it can affect code generation, so regenerate your client if you pin to the spec.
• Tag changes: OpenAPI tags that organize endpoints in the documentation can be added, changed, or removed without affecting API functionality.
• Early Access: APIs in Early Access do not guarantee backward compatibility. A breaking change to an Early Access API is a MINOR increment, and transitioning an API out of Early Access is a PATCH change.

Stay informed about changes

New endpoint versions, deprecations, and graduations from Early Access to General Availability are announced in the release notes. If you maintain a long-lived integration, watch them so you can plan version upgrades and migrations before a sunset date rather than after. For programmatic consumers, diffing the OpenAPI document between releases is a reliable way to detect changes to the surface you depend on.