# API versioning

Releases of the Investment API carry a version number. The version of the API you are currently using defines which API endpoints are accessible, what parameters and payloads they accept and what responses you will receive from them.

The version numbers we use also convey information to you about the nature of changes we have made with each release. Managing the version numbers correctly requires us to carefully check that we don't release changes that will break your solution by accident.

## Version numbering system

We use [semantic versioning](https://semver.org/) for the Investment API, in the format `MAJOR.MINOR.PATCH`.

| Version | Description |
|  --- | --- |
| `MAJOR` | We increment the `MAJOR` version when we introduce incompatible API changes and you need to start aligning your systems with the new version of the Investment API. This is, by design, a very rare event and will not happen without extended forethought, planning and client communication. |
| `MINOR` | We increment the `MINOR` version when we add new functionality in a [backwards compatible](#ensuring-backwards-compatibility) way. This is a relatively common event, and you can be sure that when you see the minor version change, this is worthy of your attention. |
| `PATCH` | We increment the `PATCH` version when we fix a bug or change something in a [backwards compatible](#ensuring-backwards-compatibility) way which does not affect existing functionality. This can happen more than once in a single day. You do not have to take action with regards to these changes unless we contact you directly about them. |


If necessary, we may deprecate functionality in favour of newer, equivalent or improved mechanism. In this case we will maintain the deprecated version for a period agreed with our clients. Deprecated functionality will typically be absent from the next MAJOR release.

Following a `MAJOR` version update, we can agree with individual clients that the old major version will run alongside the new major version for a transition period to allow for a seamless migration on your side of the integration.

After the transition period is over, the old API version will start to return a `426 Upgrade Required` error.

## How to use versioning

The API version is selected by sending an `upvest-api-version` header:


```http
upvest-api-version: 1
```

Only the `MAJOR` component is included, as `MINOR` and `PATCH` version changes are always [backwards compatible](#ensuring-backwards-compatibility).
The `upvest-api-version` header is optional and defaults to version 1.
Note that this value is *not* enclosed in quotation marks.

## Ensuring backwards compatibility

We consider these changes backwards compatible:

- Adding new API endpoints
- Adding new HTTP methods to existing API endpoints
- Adding optional request body fields
- Adding optional request query parameters
- Adding new response fields
  * Any client software is expected to gracefully handle additional properties during JSON unmarshalling / deserialisation.
- Adding new response headers
- Adding new allowed values to existing `enum`-like fields:
  * Our API models use strings to represent `enum`-like properties, i. e. fields that allow only to be set to a value chosen from a constrained list of values.
  * Any client software is expected to use a generic string for these types instead of using strict deserialisation into a well-defined enum type.
  * Any client software is expected to gracefully handle values which—at the time the client software is written—are outside of the set of allowed values.