You are using an unsupported browser. Please update your browser to the latest version on or before July 31, 2020.
close
You are viewing the article in preview mode. It is not live at the moment.
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

 

Observations

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

scroll to top icon