API and API Operation Versioning

Catalyst Center, following Cisco's API-first strategy, commits to maximizing integration value by enforcing a clear policy on breaking changes, including preventive measures and defined procedures if such changes occur.

In summary, we will:

  • Clearly differentiate between backward-compatible (non-breaking) and non-backward-compatible (breaking) changes to help developers understand their impact while developing applications that consume Catalyst Center API.
  • Avoid breaking changes as a best practice and by default.
  • Provide advance notice for any necessary breaking changes through developer communication channels.
  • Offer a clear explanation of the lifecycle for REST API operations.
This document focuses on our REST API lifecycle.

Definitions

API Operation: An API operation in Cisco Catalyst Center combines an HTTP Method (for example, GET, POST, PUT, DELETE) with a Path (endpoint URL), known as a REST endpoint. Cisco Catalyst Center previously used the term "API" in its terminology.

For example: • GET /dna/intent/api/v1/task • POST /dna/data/api/v1/assurance/networkDevicesHealth

API: An API includes all API operations that a domain or product offers. We focus on maintaining uniform version numbering across all API operations within a specific API version as much as possible.

Strategy

Catalyst Center is an on-premises application, and its overall API versioning aligns with the versioning of Catalyst Center itself.

An individual API operation within a specific API version may have its own distinct versioning, which appears in the operation path. For instance, the 'v1' in '/dna/intent/api/v1/task' indicates version 1 of the Task operation. Versioning an API operation is sometimes necessary to preserve backward compatibility while also improving the overall API experience.

Alignment Versioning

Catalyst Center periodically aligns API operation versions by designating key releases and deprecates earlier versions. Deprecated API operations stay available long enough to support migration as outlined in the deprecation process.

Deprecation

Cisco may deprecate API versions or API operations as needed. After the announced deprecation period, Catalyst Center will remove the versions or operations marked as deprecated.

Cisco offers newer, more performant alternatives over time to address developer use cases currently met in whole or in part by existing operations and/or versions.

When this happens, Cisco will:

  • Mark the deprecated operation or version as deprecated in the OAS.
  • Provide documented alternatives to the operation or version.
We encourage developers to take advantage of the improvements and migrate their applications to the latest offerings. It is the developer's responsibility to migrate their applications to non-deprecated offerings before the sunset date of that offering.

Version and Revision

API Version: An API version, also known as a major version, identifies a grouped set of API resources and operations. Catalyst Center aligns overall API versions with the Catalyst Center software version.

API Revision: An API revision, or minor version, includes non-breaking, backward-compatible improvements like new attributes or capabilities within a major version, ensuring existing clients remain unaffected.

Deprecation and Sunsetting

Deprecation: Deprecation is a standard step in the lifecycle of an API operation. It can apply to an entire API version or a part of it, like a single operation. Deprecation signals a better alternative is available, such as a newer version or operation. Deprecation is not a breaking change.

Note:

  • When Catalyst Center deprecates an API version, it issues a sunset announcement with timelines as appropriate. Migration efforts may vary. Migration efforts can vary. Using a deprecated API version is against best practice. We recommend you review your needs and consider available replacements.
  • Catalyst Center removes an API operation and its API version when it deprecates the operation and provides alternatives with superior functionality. Migrating to new operations is advantageous, especially for large environments or specific use cases. Using a deprecated API operation is against best practice and discouraged.Review your needs and consider available replacements, even if Catalyst Center has not announced a sunset date.

Sunsetting: Sunsetting is the act of removing support for a single API operation or a whole version, after the deprecation period has elapsed. An operation or version is sunset after the deprecation period has elapsed. Sunsetting is a breaking change.

Per-operation deprecation: When Catalyst Center deprecates a specific API operation, it continues to remain available for two Generally Available (GA) releases of Catalyst Center, or for 1 year, whichever is greater.

After the deprecation period concludes, Cisco reserves the right to sunset a deprecated API operation in any future release of Cisco Catalyst Center at its sole discretion.

Non-Backward Compatible (Breaking) Changes

To reduce variations in API operation versions, Catalyst Center periodically designates key releases where all API operation versions are aligned, and all previous versions are deprecated. As with any deprecation (outlined below), deprecated API operations remain available for a sufficient period to facilitate migration.

Tagging

API operations label the embedded product documentation to reflect any of the following states. DevNet content identifies these states when feasible.

Supported: The absence of a tag indicates that the current version of the API/Product fully supports the API operation. In line with Cisco's API First commitment, during regular operations, any changes to the interface of an endpoint operation in a supported API version are initially fully backward compatible. Cisco introduces non-backward compatible changes only under the circumstances outlined above.

Deprecated: As explained above, a Deprecated tag signals that a better alternative is available, such as a newer version or operation.

Sunset: A Sunset tag indicates that support for a single API operation or an entire version ends after the deprecation period elapses.

Beta: This operation is unsupported and experimental. It releases to gather feedback from early adopters. The functionality does not guarantee performance, and the design remains unfinished. Sometimes, this operation is called an Enterprise Field Trial (EFT) API operation.

Note A future release may implement (incompatible) changes to the endpoint operation's request/response payload, request path, or parameters, or may discontinue this endpoint operation entirely.