# 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.io/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.io/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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.countercyclical.io/developers/versioning.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.