Skip to content
English
Submit a request
Oxford Risk Homepage
  • There are no suggestions because the search field is empty.

API Versioning and Support Policy

API Versioning Strategy

This policy applies to Investor Compass version 4.9 and later.

New Oxford Risk API versions are released as either minor or major versions. A minor version contains no breaking changes, so consuming applications do not need to be updated to switch over to it; for a minor version, the minor version number is incremented (e.g. v4.9 to v4.10). A major version contains API breaking changes and consuming applications may need to be updated before switching over to it; for a major version, the major version number is incremented (e.g. v4.10 to v5.0).  

Contents:

Setting the API version in your application

You should control which version of the Oxford Risk API is used in your application by setting a header on API calls as shown below, replacing the number highlighted in red with the version of the API you wish to use.  

The version of the API set in the header will be used to service API calls for as long as the version is supported (see API Support Policy).


If the header is not set, the API will return the default version as shown in our documentation home page: https://docs.oxfordrisk.io/docs/


Hotfixes

Hotfixes may be issued for emergency bug fixes and security patches. These will be released for supported API versions and will not require the x-version headers to be updated.  


Hybrid customers (users of both the webapp and API)

New releases of the Investor Compass web application may also require upgrades to the API version. Where this is the case for hybrid customers, we will not automatically upgrade the web application, but will instead arrange to upgrade the web application at a mutually convenient time. In the future, we intend to allow our customers to control upgrades to the web application. Consuming applications can check the version of the frontend they are using by calling the endpoint of documented on this page: https://docs.oxfordrisk.io/docs/#tag/Version-Operations  


Breaking Changes

Oxford Risk will endeavour to keep breaking changes to a minimum, preferring where possible to make all changes backwards compatible. Breaking changes will only be introduced in major versions. If we do have to introduce a breaking change, we will add details to our API changelog page. They will also be clearly marked in the release notes for the version they appear in.  

Breaking Change Examples

• Making a previously optional parameter mandatory / Adding a new mandatory field.
• Changing the data type of a property.
• Changing an API endpoint path
• Removing an API endpoint


API Support Policy

Oxford Risk’s goal is to ensure that our customers are able to take advantage of the most up to date features, while providing sufficient time to test and manage the transition to new releases. When a new version is released, the previous version will remain available for the following periods:

  • Minor versions: 4 months after the new version is released. Minor versions contain no breaking changes, so no changes to consuming applications are needed to switch over.
  • Major versions: 9 months after the new version is released, to allow time to update, test and manage the transition.

      This policy also applies to the web application for hybrid customers. You can find the end of support dates for each version here. Once a version falls out of support, any applications calling it in their x-version header will be automatically redirected to the current version of the API.