Versioning

Overview

By versioning our API, we allow for ensuring stability and predictability for user applications when updates or changes are made.

Versioning Strategy

We use URL path versioning to manage different versions of our API. Each major version of the API is accessed via a distinct base URL that includes the version number.

URL Structure

• Base URL: https://api.countercyclical.com/

• Versioned URL: https://api.countercyclical.com/v{version}/

Example Endpoints

• Version 1: https://api.countercyclical.com/v1/investments

• Version 2: https://api.countercyclical.com/v2/investments

Requesting a Specific Version

To use a specific version of the API, include the version number in the URL path. Each version may have different endpoints, parameters, or response formats.

Example Requests

Version 1

GET https://api.countercyclical.com/v1/status

Version 2

GET https://api.countercyclical.com/v2/status

Versioning Policy

1. Major Versions: Significant changes that may break backward compatibility result in a new major version. Examples include changes to endpoint paths, required parameters, or response formats.

2. Minor Versions: Backward-compatible changes, such as adding new endpoints or optional parameters, do not require a new major version.

3. Deprecation: Older versions of the API may be deprecated but will remain available for a defined period. Deprecation notices will be provided well in advance to allow users to transition to newer versions.

Deprecation Notices

When a version is deprecated, a Deprecation header is included in the response, along with a message indicating the deprecation date and the recommended version to upgrade to.

Example Deprecation Notice

HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: true
Link: <https://api.countercyclical.com/v1/status>; rel="latest"
X-Deprecation-Date: 2025-01-01

{
  "data": "...",
  "message": "This version will be deprecated on 2025-01-01. Please upgrade to v2."
}

Transitioning Between Versions

1. Review Changes: Check the documentation for the new version to understand the changes.

2. Update Code: Modify your code to accommodate the new version's requirements, including endpoint paths, parameters, and response handling.

3. Testing: Thoroughly test your application with the new version to ensure compatibility and functionality.

4. Deployment: Deploy your updated application and monitor for any issues.

Best Practices

1. Stay Updated: Regularly check for new versions and review the changes to ensure you are using the most up-to-date and supported version of the API.

2. Graceful Transition: Plan for transitions between versions, allowing ample time for development, testing, and deployment.

3. Monitor Deprecations: Pay attention to deprecation notices and upgrade before the deprecation date to avoid disruptions.