Versioning

This guide defines Calico API breaking vs non-breaking changes. Major API version releases include changes that are not backwards compatible.

Major versions

When Calico releases a new major version, expect the following for older versions:

Documentation: Older version documentation is frozen and no longer updated.

Deprecation date: Older versions are automatically deprecated on release of a major version.

Sunset date: Older versions are sunset six months after release of new major version.

How to set the version

Versions are set in the path of the endpoint. We use major version numbers only.

https://api.getcalico.com/platform/v2/

Breaking Changes

New major versions may include:

Changing, renaming, or removing:

An API or endpoint URLs

The operations available for an endpoint

A required header or parameter to an endpoint

Fields or entities

The data type of a field or entity

Values in an enum

Non-Breaking Changes

Minor versions may include:

Adding

Data fields or entities in responses

New resource paths (no change to existing paths)

New operations to resource paths (no change to existing operations)

Optional properties in a request or response schema

New schemas

New error codes

New enums

Changing

Non-specific, non-actionable error codes to a more specific error code

Rate limits for endpoints

Version history

v2

Standardized to snake case for consistency in requests and responses

Standardized path names and operations

Added paging logic & parameters

Standardized response data model

Responses now always include, even if empty:

Page object

Data object

Error array

Other empty objects will not be passed in the results.

Data model example


{
    "page": {
        "next_uri": "string"
    },
    "errors": [
        {
            "provider_id": "string",
            "cause": "bad_request"
        }
    ],
    "data": {
        "assets": [
            {
                "asset_symbol": "string",
                ...
            }
        ]
    }
}

v1

The first version of the Calico APIs.

Major versions#

How to set the version#

Breaking Changes#

Changing, renaming, or removing:#

Non-Breaking Changes#

Adding#

Changing#

Version history#

v2#

v1#