Change management policy
Actito enhances its core products every day and we actively work to improve the usability of our Integration Framework.
As such, existing API operations are susceptible to changes. Connecting through the Actito Integration framework should therefore not be seen as a standalone project set in stone, but as one that may require some maintenance and periodic checks.
Nevertheless, Actito is committed to make the implementation of any change as transparent as possible, to work hand in hand with you and to give you time to migrate your code when necessary.
Changelog
To help you keep up with novelties, a changelog lists all updates such as the modifications applied to existing operations or the implementation of new operations.
Depending on the impact of an update, we make the distinction between breaking and non-breaking changes.
Breaking vs non-breaking changes
-
A breaking change entails a substantial behavior modification on an existing feature. By nature, it may requires you to update your code or to change the way it is implemented. As we know breaking changes cannot be taken lightly, we will avoid doing them unless absolutely required. Such cases will always be announced in advance.
-
A non-breaking change is an update that does not fundamentally impact the behavior of an existing feature. It does not require you to do any maintenance (as long as your code does not rely of parameters of changing nature, such as the order of fields, etc). Non-breaking changes are implemented regularly, without prior warning.
List of breaking changes
The following updates constitute breaking changes and will not be implemented without advance notice:
- Modifying an existing endpoint URI
- Removing an endpoint
- Removing an accepted value from a field having possible values in the request
- Adding a new required field, header, or parameter in the request
- Renaming a field
- Removing enum values
- Making a previously optional parameter or input field required
- Changing the data type of a field
- Changing field lengths past industry standard data limits (int, long, etc.)
- Changing error response code or category
- Changing auth types
- Changing API root domain
List of non-breaking changes
The following updates should not have any impacted on your existing integration. They will be implemented without prior warning:
- Adding an operation
- Adding an optional field/parameter/header/ in a request
- Adding a response field
- Adding a response header
- Adding a new option to a response (enum values)
- Changing the error message (We do not recommend parsing error messages to perform business logic. Instead, you should only rely on HTTP response codes and error codes.)
- Changing the order of fields returned within a response
- Renewing SSL certificates
- Updating accepted cipher list for SSL connection
These updates are non-breaking as long as the integration follows good practices.
We do not advise to expect strict answers/possible values to your calls, to rely on the order of fields or on error messages (instead of HTTP codes) in your developments.
Timing guarantees for continuity
If a feature must undergo a breaking change, a prior warning will be announced in the changelog at least 6 months before the update takes effect.
Some changes may have bigger impacts than others, such as modification of authentication methods, for example.
In such cases, we aim to give you a longer advance notice and to give you more time for adaptations.
After the implementation of a new feature or a new operation, we guarantee that it will be maintained as such, without announcing any breaking change, for at least 6 months (as of the release date published in the changelog).
For instance, if a new operation POST entity/{entity}/example is implemented in September 2023, a breaking change will not be announced on this operation until March 2024. With an advance notice of 6 months, a breaking change could not go into effect before September 2024.
Six months after implementation is therefore the reference period after which you should keep watch for potential changes.
Maintenance notices by e-mail
While we encourage you to keep a close eye on the changelog, we realize that breaking changes need to be brought up to your attention reliantly.
When a breaking change is announced, it will be accompanied by an e-mail notification sent to the license Admins and to the addresses associated with active API keys.
When creating an API user, Admins should take this into account and associate it with the relevant e-mail address that needs warning.
When possible, we analyze the usage logs to expressly notify only the licenses impacted by these changes.
Documented specifications
The API documentation is regarded as single source of truth regarding the specifications of all operations and we strive to make sure that all behaviors match what's documented, notably with automated spec validation for all V5 operations.
Potential fixes made to existing operations to ensure that they match the documented specifications therefore qualify as non-breaking changes.
If you spot an inconsistency between the documentation and the result of your calls, please do not hesitate to report it!
Versioning
All the latest developed operations can be recognized by the /v5/ in their path.
The philosophy of the V5 is to stick closely to standard REST API usages and to improve the consistency of their behavior between resources.
It is not planned to entirely phase out the V4 or replace it altogether with V5 operations. However, changes to single V4 operations can happen and will be announced through the process documented above.
In June 2024, the API reference was updated to reclassify all operations into business categories, regardless of the version. This reaffirms that both versions coexist and that the version is not the main distinction in the API architecture. In order not to keep overlapping operations within a category, a number of V4 operations with a V5 equivalent were deprecated, as announced in the change logs.