# 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

* **URL**: `https://api.countercyclical.io/v{version}/`

**Example Endpoints**

* **Version 1**: `https://api.countercyclical.io/v1/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**

```http
GET https://api.countercyclical.com/v1/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
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.