What is the significance of API versions in Azure DevOps?

Solution 1:

Every time a new major version of Azure DevOps Sever gets released, the APIs are versioned to ensure that calling conventions for that specific server keep working:

  • https://docs.microsoft.com/en-us/azure/devops/integrate/concepts/rest-api-versioning?view=azure-devops

For some APIs this changes nothing to the data shapes or arguments, but there can be changes in others.

The Azure DevOps Rest API documentation provides the docs for every version since TFS 2018 in the docs and you can switch between the different API versions in the table if contents:

enter image description here

enter image description here

Versions older than 4.1 are also in the docs, but stored elsewhere due to some technical season.

So, while some docs have remained stable ever since 4.1, they do receive new major versions whenever a new version of Teams Foundation Server / Azure DevOps Server was released. The Projects List API you mentioned likely hasn't changed since API version 1, there haven't been any changes in the way projects are created or stored since forever.

Other APIs have evolved much more aggressively, mostly the ones involving Pipelines, Git and Artifacts. And there you'll find real differences depending on what version you request.

Note

Azure DevOps and Azure DevOps server will sometimes behave differently depending on the version you specify. And when you leave out the version the request will use whatever latest version is available. So it's best-practice to specify the version you're expecting on order to ensure Azure DevOps processes and returns the data the way you expect it to.