You are using an unsupported browser. Please update your browser to the latest version on or before July 31, 2020.
How does API versioning work?
print icon

In some cases, an API endpoint needs to exist in more than one version. The platform supports this by inserting a version number into the URL.


For instance, if we chose to change the /api/risks/newDraft endpoint...

  • $ROOT/api/v20.02/risks/newDraft ... would be the new version, released in Feb 2020
  • $ROOT/api/risks/newDraft ... would continue to be the old version, forever
  • $ROOT/api/v21.06/risks/newDraft ... may happen, previous versions carry on


Most changes do not create a versioned endpoint.

  • Most endpoints will only have one version – vYY.MM is only for exceptional cases
  • Additions to the output format will not cause a version change
  • Optional additions to the input format will not cause a version change
  • Changes to the internal behaviour of the endpoint will not cause a version change



  • Integrated systems will have a mixture of /api, /api/v20.02, /api/v20.05 etc
  • Documentation will need to be helpful to guide integrators to use the most up-to-date version


At time of writing, February 2020, there are no versioned endpoints. This convention is being adopted to future proof the system, ensuring compatibility for integrations under development.

2 out of 3 found this helpful

scroll to top icon