Version scheme is a special feature to support the OpenAI toolkit and integration due to the issue of recognising version numbers at the end of the API URL rather than the version name. The standard version scheme called 'URL Suffix', usually puts the major version number at the end of the URL used to access the API. However, this is an issue with OpenAI toolkit integration which expects some sort of name for the any version scheme. And as a result, URL suffixes with a version number did not resolve correctly.
Introducing the version scheme detail when publishing an API, resolves this conflict between the standard version scheme 'URL Suffix' format and that expected by OpenAPI. This means when you publish a new version of an API, all you see at the end of the URL is the friendly name you have given to the version scheme and not a number as would have been the case with a standard version scheme implementation. This allows you to have more than one major versions of an API available and working concurrently.
For example, you can have more than one major version of an API by simply creating another API with the same codename but different major version (with the Major version number set to 2).
The version scheme options available for Hosted APIs are:
None - An example format is https://api.education.gov.uk/apiName
URL Suffix - This means when you publish a new version of an API, all you see at the end of the URL is the friendly name you have given to the version scheme. An example format is https://api.education.gov.uk/apiName/1 where 1 at the end of the URL represents the Major Version.
Querystring parameter - An example format is https://api.education.gov.uk/apiName?version=2025-05-01 where 'version' is the Parameter Name and '2025-05-01' is the Major Version (based on Microsoft convention for versioning APIs)
Header parameter - An example format is https://api.education.gov.uk/apiName+version=2025-05-01 where 'apiName' is the codename for the API, 'version' is the name of the Header parameter and '2025-05-01' is the value of the Header Parameter.
Here are a few Dos and Don'ts to remember when using the version scheme feature.
Dos:
- You can add a new API with a similar codename to an existing API and a Major version number, but you can set the version scheme option to 'None'. This is to help differentiate the two API versions.
- You can have an API with a single Major version and a unique Codename with a 'None' version scheme option selected.
- You can have an API with more than one version but must have the URL Suffix version scheme option selected to enable that setting. This is to prevent any confusion about which major API version is being used.
- You can have an API with 'None' Version scheme and add further versions with the Version scheme set to 'URL Suffix'. Hence, 'None' and 'URL Suffix' version schemes can coexist for the same API. This is because the extra '/' (slash) at the end of the URL which is followed by the version when using URL Suffix version scheme creates a distinction between the versions.
Don'ts:
You can't add a new API to a workspace with the same Codename and Major version number. If you do so, it will be rejected.
You can't' have an API with 'None' version scheme and added another version with the version scheme set to 'Querystring parameter'. Hence, 'None' and 'Querystring Parameter' cannot coexist for the same API. This is because the system wouldn't be able to distinguish which API version scheme to use.
You can't have an API version using a different parameter name, if you already have one with a version scheme set to 'Querystring Parameter'. This is because it will create ambiguity as to which API is being referenced.
An example would be trying to change the parameter name 'version' used for an API to 'version2'.
You can't have an API version using the same Header Parameter name, if you already have one with a version scheme set to 'Header Parameter'.
You can't have an API version using the 'Header Parameter' version scheme, if you already have one with a version scheme set to 'Querystring Parameter'. Hence, 'Querystring Parameter' and 'Header Parameter' can't coexist for the same API.
you can't have an API version using the 'Querystring Parameter' version scheme, if you already have one with a version scheme set to 'Header Parameter'. Hence, 'Header Parameter' and 'Querystring Parameter' cannot coexist for the same API.
The table below summarises the combination of API version schemes that are valid.
| 1st API version scheme + Nth API version scheme | Valid? | Notes |
|---|---|---|
| 'None' + 'None' | Yes | Adding an initial API version scheme as 'None' and adding another as 'None' can coexist, hence valid. |
| 'None' + 'URL Suffix' | Yes | Adding an initial API version scheme as 'None' and adding another as 'URL Suffix' can coexist, hence valid. |
| 'None' + 'Querystring parameter' | No | Adding an initial API version scheme as 'None' and adding another as 'Querystring parameter' can't coexist, hence invalid. |
| 'None' + 'Header parameter' | No | Adding an initial API version scheme as 'None' and adding another as 'Header parameter' can't coexist, hence invalid. |
| 'URL Suffix' + 'URL Suffix', | No | Adding an initial API version scheme as 'URL Suffix' and adding another as 'URL Suffix' can't coexist, hence invalid. |
| 'URL Suffix' + 'Querystring parameter', | No | Adding an initial API version scheme as 'URL Suffix' and adding another as 'Querystring parameter' can't coexist, hence invalid. |
| 'URL Suffix' + 'Header parameter', | No | Adding an initial API version scheme as 'URL Suffix' and adding another as 'Header parameter' can't coexist, hence invalid. |
| 'Querystring parameter' + 'Querystring parameter', | Yes | Adding an initial API version scheme as 'Querystring parameter' and adding another as 'Querystring parameter' can coexist, hence valid. |
| 'Querystring parameter' + 'Header parameter', | No | Adding an initial API version scheme as 'Querystring parameter' and adding another as 'Header parameter' can't coexist, hence invalid. |
| 'Header parameter' + 'Header parameter', | Yes | Adding an initial API version scheme as 'Header parameter' and adding another as 'Header parameter' can coexist, hence valid. |