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.If we find any security issues or a bug that has an important impact in the correct operation of our product we will make changes as soon as posible, according to the Service Level Agreement.
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 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
