Links

Deprecation Notices

List of changes impacting the usage of the CLI and API

What is a deprecation notice?

During the development of an API, some changes must be made that can break the previous usage of a feature. Examples of breaking changes to an API can include, but are not limited to:
  • removing a field from an object, or an endpoint from the API
  • renaming a field or an endpoint
  • marking a field as a required input (new or existing fields)
A deprecation notice is an announcement about a change in the API that directly impacts how one can use a given feature. The deprecation notice describes what feature is impacted, the new way to use the feature (if any), and a timeline of when the support for the deprecated feature will be removed from the API and CLI.

60 days to update your scripts

Optable strives to provide backward compatibility support for a minimum of 60 days before implementing breaking changes (exceptions to the duration may be made on a case-by-case basis). This means that if a feature is marked as deprecated (for example, by removing an endpoint), it may be removed after 60 days from its release, and Optable does not guarantee that it will continue to work. During this time, the endpoint will continue to operate as usual for backward compatibility purposes. This allows clients approximately two months to update their scripts and usage of the API/CLI in accordance with the deprecation notice.

Deprecation Notices:

December 8th, 2022: Exports to Export Configurations

Starting v9.27.0, released December 8th, 2022 some features will be marked as deprecated with regard to the export commands. The deprecated features listed below will be removed as of v10.0.0 of the API and CLI, which is planned to be effective on the week of the 13th of February.
Impacted versions: API and CLI v9.27.0 and lower
Timeline: Monday the 13th of February
Subject: Export configuration are introduced to allow users to configure their export with a schedule (and more). This means, an export configuration may be scheduled to run only once, or on a recurring pattern (daily, weekly). With this change, the relations between an export and a destination have changed and requires a breaking change in the API and CLI. Now, a destination may have many export configurations, and each export configuration may have many exports. CLIs version v9.27.0 and higher will offer both the export commands and export-configuration commands, to allow a smooth transition.

Deprecated uses in the CLI

Export Create

Deprecated
New
optable-cli export create
optable-cli export-configuration create
The set of arguments and flags to pass has changed too, be sure to check optable-cli export-configuration create --help (on v9.26.0 and higher) to know the list of possible options.
For backward compatibility, commands made with optable-cli export create will create an export configuration using the given audience and destination and automatically configure its schedule to run only once with a start time equal to "now".

Export retry

optable-cli export retry command is removed. A failed export should not be retried in-place, because it can obfuscate the initial error. Instead, a new export must be made, keeping track of all attempts (even those that failed) for audit reasons.

Migration of existing exports

All existing exports will be transitioned to the new data structure by being automatically associated to an export configuration with a schedule "run once" and a run date equal to the date the export happened. The state, error, and all other attributes of existing exports will be retained and visible in addition to the new export configuration features.