# Versions

### Specifying API version

The API is versioned using root path versioning in the format `/v{version}` . For example `/v1/transfer` .

### Supported API versions

The following REST API versions are currently supported:

`v0.5` -> [swagger docs](https://api.carbonregistry.com/v0.5/openapi)

`v1` -> [swagger docs](https://api.carbonregistry.com/v1/openapi)

The following REST API versions are deprecated:

`v0` -> [swagger docs](https://api.carbonregistry.com/v0/openapi)

### About API versioning

Any breaking changes will be released in a new API version. Breaking changes are changes that can potentially break an integration. Breaking changes include:

* removing an entire operation
* removing or renaming a parameter
* removing or renaming a response field
* adding a new required parameter
* making a previously optional parameter required
* changing the type of a parameter or response field
* removing enum values
* adding a new validation rule to an existing parameter
* changing authentication or authorization requirements

Any additive (non-breaking) changes will be available in the newest API version - they could be available in older versions but don't count on it. Additive changes are changes that should not break an integration. Additive changes include:

* adding an operation
* adding an optional parameter
* adding an optional request header
* adding a response field
* adding a response header
* adding enum values

When a new REST API version is released, the previous API version will be supported for at least 6 more months following the release of the new API version, and we expect our integration partners to migrate to a newer version inside this depreciation timeframe.