API Versioning

Important: Understanding and adhering to API versioning is crucial for maintaining compatibility and ensuring a smooth transition for your applications as the API evolves.

Why Versioning?

As our APIs evolve, we may need to introduce changes that are not backward-compatible. Versioning allows us to manage these changes without disrupting existing integrations. By explicitly requesting a specific API version, you can control when and how your application adopts new features or breaking changes.

We are committed to providing a stable API. Versioning is a key part of this commitment, allowing us to innovate while giving our developers predictable upgrade paths.

Versioning Strategy

Our API uses a URL-based versioning strategy. Each version of the API is identified by a version number (e.g., v1, v2) appended to the base URL. This makes it clear which version of the API a client is interacting with.

Current Major Versions

  • v1: The initial stable release. Focuses on core functionalities.
  • v2: Introduced significant performance improvements and new features. Recommended for new integrations.

How to Specify a Version

You can specify the API version by including it in the URL path:

GET https://api.msdn.example.com/v1/resource
GET https://api.msdn.example.com/v2/resource

If no version is specified, the API will default to the latest stable version (currently v2).

Deprecation Policy

We will provide ample notice before deprecating older versions of the API. Typically, a deprecated version will be supported for at least 12 months after the announcement of its deprecation.

During the deprecation period, the deprecated API version will continue to function, but it will no longer receive new features or significant updates. We strongly advise all users to migrate to a newer, supported version as soon as possible.

Version Compatibility

Within a major version (e.g., v1), we strive to maintain backward compatibility for all minor updates and patch releases. This means that if you are using v1.0.0, you should generally be able to upgrade to v1.1.5 without breaking changes.

Breaking changes will only occur when introducing a new major version (e.g., moving from v1 to v2).

Example of Versioned Request

Fetching User Data

To fetch user data using version 1:

GET https://api.msdn.example.com/v1/users/12345

To fetch the same data using version 2:

GET https://api.msdn.example.com/v2/users/12345

Future Considerations

We are continuously evaluating our versioning strategy to ensure it meets the needs of our developer community. Potential future strategies might include:

  • Header-based versioning for more granular control.
  • Deprecating old versions with a phased approach.

We will communicate any significant changes to our versioning policy well in advance through our official developer channels and the Changelog.