Notifications regarding breaking changes in the Production environment

[#1]

A breaking change in an API end-point usually means that we either improve the end-point itself or that we improve the underlying functionality to the better by changing the business logic in the application. The change is considered a breaking change when the function or signature of the endpoint is changed in such a manner, that an integration using the endpoint can no longer expect the same result as before (see document “Visma.net API ERP - Best Practice for ISVs” for more details). Such changes are a part of a product development life cycle and without it there will be less improvements/innovations in the solution.

When that is said; Visma as a vendor has to minimize the impact on ISV/Integrators and their users as much as possible, and this chapter describes what we do in these scenarios and how we do the communication.
 
The severity of the issue that caused a breaking change will affect how quickly a fix or an improvement is rolled out. In special scenarios (security or critical bug) can an endpoint also be blocked for further use. In other scenarios we plan this well ahead together with our ISV/Integrators and the user of the service will not notice that there is a change.

Security issue
A security issue is typically an error that potentially makes the end-point security weak or can be misused by a 3 party to get access to data that is not theirs.

The severity of the security issue determines what happens next and how quickly efforts are taking effect for integrators and customers.

An insecure end-point can be quarantined, changed, removed, deprecated, or be replaced by a new end-point at any time as long as the severity is high. If such an action is needed then ISV/Integrators will, as quickly as possible, be informed via the ISV/Developer forum.

Critical bug
A critical bug is an error in the solution that leads to damage of data (data inconsistency) in for instance a customer's database. In such scenarios it will be important for the vendor to stop the unwanted traffic as quickly as possible and at the same time roll out an updated solution as quickly as possible.

This will usually be solved by rolling out an updated solution with a new version of the end-point alternatively a completely new end-point.The old end-point (with a critical bug) will be kept alive in up to 1 week after the release of the updated/new end-point is communicated unless something else is communicated specifically. A critical bug can in special scenarios also lead to blocking the end-point for further use.

Planned breaking changes
Planned breaking changes in the API are usually related to a change in a feature and/or the underlying business logic that leads to an end-point not behaving the same way after the change.

These changes we strive to notify ISVs up to 3 months before the change takes effect. The ISV/Developer forum will be the communication channel for these types of changes (Swagger API documentation, Blog post and Release Notes).  

A planned breaking change usually means that we roll out a new version of the end-point or a new end-point, and then the ISV/Integrator will have up to 3 months to update their integration to reflect the breaking change. After 3 months the old endpoint will be deprecated and stop working.