API compatibility policy and deprecation policies

On occasion, Qmatic may choose to retire a service offered in the API Manager. This may be because the future roadmap for the service requires breaking changes (thus demanding a new major version), or because the service depends on, or relates to, user-facing product capabilities that are being retired.

When a breaking change is introduced to the Appointments Manager API, a new dated version will be released. To avoid breaking the client’s code, the version should not be changed before the integrated client is ready to upgrade.

Backwards-compatible changes

These changes are generally safe for the customers. However, the change must consider popular client frameworks that might generate a code that conflicts with this change.

Cloudberry Qmatic developers team consider the following changes to be backwards-compatible:

• Adding new API resources

• Adding new optional request parameters or headers to existing API methods

• Adding new properties to existing API resources

• Changing the length or format of opaque strings such as object IDs, error messages, and other human-readable strings

This includes adding or removing fixed prefixes.

• Changing an error message and resource descriptions in the API response

• Increasing the scope of error message ID

• Rate-limit headers and errors.

• Adding new event types

Breaking changes (examples)

• Removing or renaming an API source

• Removing or renaming Enum values

• Changing the type of a field

• Changing the visible behaviour of existing requests

Deprecation policy

The following notifications are given to mitigate potential issues when API is deprecated. The deprecation period is 12 months.

Notice of deprecation

Notice of deprecation are issued through the internal and external channels at least 12 months before the proposed end life date. The notice should contain a notification about the deprecation with the links to more detailed info, including the deprecated version, the replacement version the end-of-life date. Deprecation announcements will be accompanied by guidance on how to respond if your application is impacted by the announcement, including a migration guide if a new major version is available or recommendations of alternative third-party services where possible.

The notification continues until the APIs reach the end-of-life date. Once the date is reached:

• Documentation content for the old version will be removed

• Swagger documentation for the deprecated API will be removed or hidden

At the end of the deprecation period, the service concerned will be retired and no longer be accessible to applications. After this date, any attempt to use the service will fail. All documentation for the service will also be taken offline.

Swagger

Swagger defines the API contract to customers. The APIs that are being deprecated are marked with the tab “deprecated “.

Upgrade reference instructions for client

The possibility to roll back for 72 hours

Informing about the updates

The information about the new additions and changes to Appointments Booking API should be posted to our channels of communication. Possibility to subscribe and stay informed should be provided. or the process of client notifications should be established.

Changelogs

Changelogs should be introduced. Changelog list should include all additions and APi updates in chronological order.