Versioning

Versioning on the Investment API defines how to call the API, what functions are accessible, and what to receive back from calling the Investment API. We version the Investment API such that we can release new functionality without breaking existing integrations or requiring you to immediately upgrade.

How versioning works

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.
  • We increment the MINOR version when we add new functionality in a backwards compatible way.
  • We increment the PATCH version when we fix a bug or change something in a backwards compatible way which does not affect existing functionality.

For each MAJOR version upgrade, the old major version will live side by side with the new major version during a transition period to allow 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