Policy for Important API Changes

July 16, 2022

As our API evolves, important changes or "breaking changes" can occur that can impact your integration.

Every day, updates are made to the applications we use on our mobile devices and computers. And our code is also affected by these updates. Whether to correct an error or to update a functionality, versioning allows us to offer new features and improvements without affecting previous integrations.

When we talk about mobile or desktop applications, new versions and patches can be launched to implement changes minor, medium, or major. However, for APIs, it is not possible to offer multiple simultaneous versions and to keep them indefinitely for all of their users. Based on this context, the concept of an important change breaking change is established.

Breaking changes

An important change or breaking change is one that may require you to update your application to avoid interruptions in your integration.

These types of changes are notified in advance to your bussines so that you can have enough time to perform any required updates and avoid any interferences in the service.

We will inform you about these changes at least 4 months in advance so you can make the necessary updates before we release a new version for production.

These changes can be classified as follows:

• Changes to existing permissions
• Removal of parameters, answer fields or request fields that were previously allowed
• Addition of new parameters or any necessary request fields, which will not have default values. This could change the interaction when calling a function; since the number of fields needed for the request are not available, we will not obtain a response, or an error will be returned as an answer
• Changes to an endpoint final functionality
• Addition of a new validation
• Removal or renaming of an endpoint, field, or listed value
• Change the type of a field
• Change the URL format in the HTTP definition
• Change an optional field to a required field in the request

Non-breaking changes

In contrast, “non-breaking changes” are those that you can adapt at your discretion and rhythm, without suffering interruptions in your integration. Most of them are introduced without prior notification. Make sure your application or integration is designed to manage these types of changes.

Generally, if we make a change classified as “non-breaking”, the current service or product will continue to work normally without the need to make updates in the integration.

These are the changes that we can make and that we think will not affect your integration:

• Addition of a new endpoint
• Addition of a new method to an existing endpoint
• Addition of new fields in the following scenarios:
  • New fields in responses
  • New request fields or optional parameters
  • New required request field that will contain default values
• Addition of a new value returned by an existing text field
• Changes in the order that are returned by response fields
• Addition of an optional request header
• Removal of redundant header fields
• Changes to the length of the information returned by a field
• Changes to the average size of a response
• Changes to error messages. (We recommend parsing response codes or errors instead of parsing error messages directly in your integration)
• Changes in response or error codes, switching from an incorrect to a correct value
• Addition of a new value to an enumeration or enum