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.