OpenAPI versioning

Infobip uses Semantic Versioning (MAJOR.MINOR.PATCH) for its OpenAPI documents. This versioning applies to the OpenAPI specification itself, not to individual API endpoints — endpoint changes are reflected in the API's own versioning scheme.

Version change types

MAJOR versions indicate structural changes to the OpenAPI specification, such as upgrading to a new OpenAPI standard version, altering the naming scheme of schema components, or modifying the general security scheme.

MINOR versions introduce backward-compatible functionality. This includes:

• Adding new endpoints
• Deprecating existing endpoints (with advance notice)
• Adding optional request parameters or response fields
• Introducing new enum values through opt-in mechanisms
• Adding new response codes or reusable components

PATCH versions address documentation improvements: fixing inconsistencies between the specification and actual API behavior, correcting typos, clarifying descriptions, updating examples, and adding OpenAPI extensions for metadata.

What to expect as a consumer

When integrating with Infobip APIs, keep these practices in mind:

• Ignore unknown fields — Your implementation should gracefully handle new optional parameters or response fields it doesn't recognize.
• Plan for deprecations — Deprecated endpoints remain functional during a grace period. Monitor deprecation notices to update your implementation before sunset.
• Use method and path for identification — Rather than relying solely on operation IDs, use the HTTP method and path combination to identify API operations, as operation IDs may change to reflect the latest API version.

Special cases

Sunset endpoints — Removing deprecated endpoints after their grace period is a MINOR version change for the OpenAPI document, though it is not a breaking change for clients who followed the deprecation notice.

Schema renames — Component schema names may occasionally change for clarity or consistency. While this can affect code generation, it does not change API behavior.

Tag changes — OpenAPI tags used for organizing endpoints in documentation may be added, modified, or removed without affecting API functionality.

Early Access products — APIs in Early Access don't guarantee backward compatibility. Breaking changes during this phase are treated as MINOR version bumps. Transitioning out of Early Access is a PATCH change.

Product-level specifications

In addition to the unified OpenAPI specification, product-specific specifications are available (for example, for SMS). These inherit their version from the main specification and do not have independent versioning.