Backward compatibility

Backward compatibility means that when Infobip updates an API, code that already works keeps working. An update does not remove a field you depend on, change a response shape, or alter the meaning of a status code. It lets you benefit from improvements without having to rewrite your integration every time the API changes.

Infobip evolves its APIs over time while maintaining backward compatibility.

What Infobip commits to

For Generally Available APIs, Infobip commits to the following:

• Only add new fields to request models as optional. Existing requests without those fields continue to work.
• Never remove, rename, or change the type of an existing response field.
• Never change the meaning of an existing status code or error response.
• Provide advance notice before an endpoint is deprecated or sunset, with a migration path to the replacement.

For how that notice is delivered and how the sunset date is set, see Deprecation. For how API versions are structured and what each version increment signals, see API versioning.

What your integration must handle

Even within a backward-compatible API, some changes can break an integration if it is not written defensively. The following patterns keep your code resilient to routine API updates.

New fields in responses [#new-fields-in-responses-what-your-integration-must-handle]

Infobip can add new fields to response models at any time. Your parsing implementation must ignore fields it does not recognize rather than treating them as errors. This way, you benefit from new response data without needing to update your code for every release.

For example, a response that originally looks like this:

can later include an additional field. Your code handles this extended response without changes:

New enum values [#new-enum-values-what-your-integration-must-handle]

Enum values are backward compatible for existing use cases. Existing integrations can rely on the documented values, and Infobip introduces new enum values only when it adds new use cases. Include a default or fallback path for unexpected values so you can log or ignore them rather than failing the request.

JSON property order [#json-property-order-what-your-integration-must-handle]

The JSON specification does not guarantee the order of properties in an object. Read properties by name, not by position. The standard JSON library for your language handles this correctly by default.

Date formats [#date-formats-what-your-integration-must-handle]

The API returns date-time values in ISO 8601 with a time-zone offset (see Dates and times for the canonical format). For forward compatibility, accept any time-zone offset. Convert date strings to the native date-time type in your language on receipt, and let that type handle time-zone normalization.