Countercyclical Docs
  • Welcome to Countercyclical
  • Guides
    • Terminology
    • Platforms
    • Integrations
      • Airbyte
      • Google Drive
      • Google Sheets
      • Zapier
  • Fundamentals
    • Workspaces
    • Navigation
      • Command Palette
      • Exploration & Recents
      • List vs. Grid View
      • Quick Actions
    • Search
      • Filters
      • Companies
        • Charts
      • Economic Data
      • Model Syncing
    • Investments
      • Tabs
        • Overview
        • Analysis
        • Valuations
      • Actions
      • Comments
      • Invitations and Sharing
        • Share
      • Quick Versioning
    • Valuations
      • Sensitivity Analysis
      • Assumptions
    • Memos
      • Sources
    • Teams
    • Pipelines
    • Profile
    • Settings
      • Account
        • General
          • Connected Accounts
            • Google Sheets
            • Google Drive
        • Preferences
        • Notifications
        • Sessions
        • Account Security
        • Plans
      • Workspace
        • General
        • Advanced
          • Access
          • Identity
          • Appearance
          • Usage
          • Developers
        • Permissions
        • Integrations
        • Workspace Security
          • SAML SSO
          • Audit Logs
        • About
  • Use Cases
    • For Analysts
    • For Research Teams
    • For Organizations
    • For Education
  • Developers
    • Getting Started
    • Authentication
    • Rate Limiting
    • Versioning
    • Endpoints
      • Investments
      • Valuations
      • Memos
      • Teams
      • Assumptions
      • Pipelines
    • Webhooks
  • Extras
    • Security
    • Billing
    • Imports
      • Formatting Guide for Imports
    • Exports
      • Export User Data
    • Enrichment Data
    • Troubleshooting
  • Links
    • Website
    • Dashboard
    • Request a Demo
    • LinkedIn
    • Twitter / X
    • Dribbble
Powered by GitBook
On this page
  • Overview
  • Versioning Strategy
  • URL Structure
  • Requesting a Specific Version
  • Versioning Policy
  • Deprecation Notices
  • Transitioning Between Versions
  • Best Practices
  1. Developers

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

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

PreviousRate LimitingNextEndpoints

Last updated 8 months ago