Cisco Evolved Programmable Network Manager API
Evolved Programmable Network Manager API Documentation

API Versioning

This API is versioned. From time to time, we'll introduce a new version of the API. This page walks through our approach to versioning, how different versions are presented in the documentation, and what you can expect when switching your client between different API versions.

Our Approach to Versioning

Because this is an API, we avoid making changes that will break your API clientin other words, your API client should be forwards compatible with newer versions of the product and the product should be backwards compatible with existing client. However, from time to time, we will find it appropriate to make backwards incompatible changes. When this need occurs, as much as is practicable, we'll introduce the backwards incompatible changes in a new API version.

We'll often make these backwards incompatible changes to address problems around performance, remove superfluous response or request parameters, restructure request or response documents to make them more meaningful, or change the behavior of an API resource. We'll also introduce new API versions to make changes that affect the entire API, and not just one particular resource. For example, we may change the provider of JSON output and input handling in a new API version, or change the way we handle paging, or change the way we handle errors in some cases.

We'll also make changes that we believe to be backwards compatible without introducing a new API version. For example, we'll sometimes add new optional request parameters, add new response parameters, and of course, new API resources without introducing a new API version. We strongly suggest that API clients be written to ignore unexpected response parameters; for instance, if you consume XML responses, then use XPATH to pick out the elements that you're interested in. There also may be changes to the whitespace in our response documents (for example, XML may be sent with or without indentation and newlines between elements) that make it into an existing API version.

When a new API version is introduced, previous undeprecated versions will still be available. Again, the goal is to reduce disruptions and keep your existing API client compatible with new product versions. However, we suggest that you update your API client to use the latest API version, whenever a new API version is introduced.

Eventually, we may deprecate an older API version. When we do so, we'll give you clear notice of the deprecation in this documentation (on the landing page and elsewhere). In that notice, we'll let you know in which release of the product we plan on removing that API version.

How Different Versions are Presented

In order to ensure you know how an API version affects a resource that you use or intend to use, we've made some enhancements to the documentation. We've enhanced the list of all API resources, as well as the documentation page for each specific resource, to clarify which versions of the API a particular resource is available in, and in which versions it experienced major changes.

On the page that lists all of the API resources, we've added a new column on the right hand side called "API Version." For each resource listed on the page, all of the active versions of the API will be listed. If a resource is available for a particular version, the version will be a hyperlink to the documentation for that resource and API version. We also use color coding; gray for a version that a resource is not available in, dark blue for the version a resource was introduced or underwent a significant change in, and light blue for a version that the resource is available in but had no significant changes since the last version. Here's an example

So, in the above example, a hypothetical resource is unavailable in v1, introduced in v2, underwent no significant changes in v3, had some significant changes in v4, and then was removed in v5. Accessing this hypothetical resource at the v1 and v5 URLs would result in an error. Accessing it via the v2 and v3 URLs will result in the same behavior (of the resource, the different API versions might have changes affecting the whole API, as discussed above). Lastly, accessing it by the v4 URL will result in different behavior than by the v2 and v3 URLs.

For the pages that document each resource, we've used the same color scheme as above to highlight which API versions the resource is available in, and which it has experienced significant changes in. Furthermore, we've added some text that appears above the tables for request and response parameters that clarifies if a particular version introduced significant modifications to the resource.

What You Can Expect When Switching Your Client Between API Versions

As discussed above, we recommend using the latest version of the API in your client (especially for all new development). However, switching your client over to new versions may require changing the implementation of the client, and should always be tested before going live.

In order to better understand what has changed across the whole API for a new version, we recommend checking out the What's New page (in fact, we recommend checking that page out after every upgrade of the product). The What's New page has a summary of what was changed in every version of the product, and when new API versions are introduced, it will let you know what changes they bring.

While the What's New page will inform you of the details, you should know that we will sometimes introduce major changes in a new API version. The changes could include (but might not be limited to): authentication and session management, authorization and access control, in what cases we present errors and how we present them, the format and structure we expect request payloads to be in, the format and structure we return responses in, and how particular types of values (like dates, times, decimal values, addresses, etc.) are represented.

Furthermore, for each API resource that you use, check the documentation page dedicated to it. Review the documentation for the version you are using, and for the latest version, and note any differences. Generally, you can expect changes to a particular resource to include new request parameters (optional or required), removed response parameters, changes in the data accepted by a request parameter, added response parameters, moved or removed response parameters, changes in data types for existing response parameters, changes in behavior for services and changes in their output.