# 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**

```json 

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

```

### v1
The first version of the Calico APIs.

<p class="text-xs text-right">1249407.1.0</p>