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.

Our version numbering system

We use semantic versioning for the Investment API, in the format MAJOR.MINOR.PATCH.

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

  • We increment the MINOR version when we add new functionality in a backwards compatible 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.

  • We increment the PATCH version when we fix a bug or change something in a backwards compatible 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

Selecting the right API version to send requests to

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

upvest-api-version: 1

Only the MAJOR component is included, as MINOR and PATCH version changes are always backwards compatible. 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.

Was this page helpful?

On this page