Skip to main content

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 routes 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 routes or the implementation of new routes.

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
tip

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.

Note

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 route, 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 route POST entity/{entity}/example is implemented in September 2023, a breaking change will not be announced on this route until March 2024. With an advance notice of 6 months, a breaking change could not go into effect before September 2024.

info

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.

tip

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 routes and we strive to make sure that all behaviors match what's documented, notably with automated spec validation for all V5 routes.

Potential fixes made to existing routes to ensure that they match the documented specifications therefore qualify as non-breaking changes.

tip

If you spot an inconsistency between the documentation and the result of your calls, please do not hesitate to report it!

Versioning#

Note on V4 and V5

All the latest developed routes 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 routes. However, changes to single V4 routes can happen and will be announced through the process documented above.