API Deprecation Policy

Epsilon Retail Media's documentation is now centralized with our knowledgebase!

For up to date guides, please view this page in the new Partner APIs space of our documentation.

Why we deprecate

Here at Epsilon Retail Media we constantly iterate and introduce new products and features. As such, changes to our APIs will be inevitable. To help our users to plan for changes, we follow a deprecation policy where a better version is available or a feature is nearing or at the end of support.

The deprecation period for a version begins on the announcement date for the deprecation. The versions marked for deprecation will continue to be available throughout the deprecation period of 3 months. Once the deprecation period has elapsed, the version is expected to be decommissioned, and Epsilon Retail Media can no longer guarantee it will be available from the sunset date.

Deprecation enforced rules for our APIs

1. Breaking changes such as removed API elements are only introduced through incrementing the version of the API.

   • Once an API element has been added at a particular version, it can not be removed from that version or have its behaviour significantly changed

2. API objects must be able to round-trip between API versions in a given release with minimal to no information loss, with the exception of whole REST resources that do not exist in some versions.

   • Example, an object can be written as v1 and then read back as v2 and converted to v1, and the resulting v1 resource will be identical to the original. The representation in v2 might be different from v1, but the system knows how to convert between them in both directions. Additionally, any new field added in v2 must be able to round-trip to v1 and back, which means v1 might have to add an equivalent field, map to an equivalent field or represent it as an annotation.

   • With Significant product feature changes we will make every effort to design our APIs to be backwards compatible but there may be exceptional circumstances where this may not be possible. We will discuss these exceptions with our partners.

3. An API version may not be deprecated in favour of a less stable API version.

   • A General Availability (GA) API version can replace the less stable Alpha and Beta versions

   • Beta versions can replace earlier Beta or Alpha versions but may not be used to replace a GA API version

   • Alpha versions can replace earlier Alpha versions but may not be used to replace a Beta or the GA version

4. API versions marked for deprecation will be supported for up to 3 months from the notice date. We will announce when the support and availability of the version will end. Alpha and Beta versions may be deprecated sooner as a preferred GA API version is introduced.

• New API versions will only be introduced as part of a release that supports both the new version and the previous version

• This allows time for users to migrate to the latest version or roll back when needed within the period of time that the previous version is no longer available and has been decommissioned

1. Calling on a decommissioned version can result in unpredictable behaviour or invalid response.

Exceptions

A policy cannot cover every possible situation. This is a living document, and will always evolve with time. Where there are situations that do not fit neatly into this policy, or for which this policy becomes a serious impediment, discuss the challenge with the team at [e-mail] to find the best solutions for those specific cases. Epsilon Retail Media is committed to providing a stable integration that, as much as possible, does not disrupt our users. Exceptions will always be announced in all relevant release notes.