API lifecycle & deprecation policy¶

Last updated on: Thurday 4 April 202

This article describes the support and breaking change policies for the versions of the Marigold Engage APIs that are currently available.

The API Lifecycle & Deprecation Policy is part of our API terms and conditions of use. We may make periodic updates to this Policy, at which time we will notify those who have agreements with us.

API Lifecycle & Deprecation Policy¶

The Marigold Engage APIs follow a Lifecycle Policy.

As new versions of the Marigold Engage REST APIs are released, earlier versions will be retired. Marigold Engage will declare a version as deprecated at least six (6) months in advance of retiring an API.

When we increment the major version of the API (for example, from v1 to v2), we are announcing that the current version (in this example, v1) is immediately deprecated, and we will no longer support it 12 months after the announcement. We might make exceptions to this policy for service security or health reliability issues.

When an API is marked as deprecated, we strongly recommend that you migrate to the active version as soon as possible. In some cases, we will announce that new applications will have to start using the new APIs a short time after the original APIs are deprecated. In those cases, only active applications that currently use the deprecated APIs can continue to use them.

API Lifecycle status¶

• Preview: An upcoming API release with new features and/or new endpoints, which might result in a new API version or an upgrade of the "active" version.
• Active: An active API version is the most current and fully supported API. It is the recommended version to use by everyone.
• Deprecated: A deprecated API version has been superseded by a newer API version. It is supported (bug fixes) for six (6) months from the deprecation date. New apps will be denied access to deprecated APIs.
• Retired: A retired API version is no longer supported. It includes any API deprecated for more than six (6) months. Any application using a retired API must migrate to an active API.
• Decommissioned: A decommissioned API version is no longer available on production. This occurs after three (3) months of inactivity in a Retired state.

API Lifecycle stages¶

The "Preview" stage is to expose access to new features & endpoints on APIs that are not yet in general available. For more information about the development stages when an API is in Preview mode, please see release stages.

API contract and non-backward compatible changes¶

Engage has a log of changes across releases. These changes are listed in the changelog that is part. As new functionality and data are added to Marigold Engage , we will change the Marigold Engage API version number for any non-backward compatible changes to the API.

The following are examples of non-backward compatible changes:

• Changes to the URL or fundamental request/response associated with a resource
• Removal, rename, or change to the type of required declared property
• Removal or rename of APIs or API parameters
• Addition of a required request header

The following are examples of backward-compatible changes:

• Addition of properties that are nullable or have a default value
• Addition of a member to an enumeration
• Removal, rename, or change to the type of open extension
• Removal, rename, or change to the type of annotation
• Introduction of paging to existing collections
• Changes to error codes
• Changes to the order of properties
• Changes to the length or format of opaque strings, such as resource IDs

Deprecated and unsupported versions¶

There are currently no deprecated versions of the Marigold Engage APIs.

Overview of API Versions¶

Terms of use¶

By using the EngageAPIs, you agree to the Engage APIs Terms of Use.