API and API Operation Versioning

As part of Cisco's API-first strategy, Catalyst Center is committed to optimizing the value of your integrations with its API offerings. In adherence to our API contract, we have defined a clear policy regarding breaking changes, detailing the preventative measures in place and the process we follow should such changes become necessary.

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 APIs.
  • 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: In Cisco Catalyst Center, an API operation refers to the combination of an HTTP Method (e.g., GET, POST, PUT, DELETE) and a Path (or endpoint URL), often referred to as a REST endpoint. Within Catalyst Center terminology, this was historically known as an API.

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

API: An API refers to the complete set of API operations offered by a domain or product. 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.

Within a specific API version, an individual API operation may have distinct versioning, which is reflected in the operation path. For example, the 'v1' in '/dna/intent/api/v1/task' signifies version 1 of the Task operation. In certain scenarios, versioning an API operation becomes essential to maintain backward compatibility while simultaneously enhancing the API experience.

Alignment Versioning

To reduce variations in API operation versions, Catalyst Center will periodically designate key releases where all API operation versions are aligned, and earlier versions are deprecated. As part of the deprecation process (outlined below), deprecated API operations will remain accessible for a sufficient period to allow for migration.

Deprecation

Cisco may deprecate API versions or API operations as needed. After an announced deprecation period, the versions or operations marked as deprecated will be removed.

Cisco may offer 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 prior to 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, also known as a minor version, identifies non-breaking improvements to an API, such as the addition of new attributes or capabilities to extend existing operations within a major version. In most cases, changes made between revisions within a single version are additive and remain backward compatible ensuring they do not disrupt or affect clients built on earlier revisions of that version.

Deprecation and Sunsetting

Deprecation: Deprecation is a standard step in the lifecycle of an API. 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 an API version is deprecated, a sunset announcement with timelines will follow when appropriate. Migration efforts can vary. Using a deprecated API version is against best practice. We recommend you review your needs and consider available replacements.
  • When an API operation is deprecated, with indications that superior operations are available, it will be sunset with its API version. 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. We recommend you review your needs and consider available replacements, even if a sunset date has not been announced.

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 will continue 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 the API operation versions, Catalyst Center will periodically designate key releases where all API operation versions will be aligned, and all previous versions will be deprecated. As with any deprecation (outlined below), deprecated API operations will remain available for a sufficient period to facilitate migration.

Tagging

API operations will be labeled in the embedded product documentation to reflect any of the following states. Content on DevNet will be similarly identified as soon as feasible.

Supported

The absence of a tag indicates that the API operation is fully supported in the current version of the API / Product. 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 will initially be fully backward compatible. Non-backward compatible changes will only be introduced 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

As explained above, a Sunset tag indicates that the support for a single API operation or a whole version is removed, after the deprecation period has elapsed.

Beta

Unsupported and experimental. Released to gather feedback from early adopters. Functionality is not guaranteed, and the design is not final. This operation is sometimes referred to as 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.