Control de versiones de la API REST

Azure DevOps Services | Azure DevOps Server 2022: Azure DevOps Server 2019 | TFS 2018

Con las API REST con versiones, puede asegurarse de que los proyectos son escalables y fáciles de mantener con el tiempo mientras las aplicaciones y los servicios siguen funcionando a medida que evolucionan las API.

Directrices

  • La versión de API debe especificarse con cada solicitud.
  • Las versiones de API tienen el formato {major}. {minor} [-{stage}[.{ resource-version}]] : por ejemplo, 1.0, 1.1, 1.2-preview, 2.0.
  • Aunque una API está en versión preliminar, puede especificar una versión precisa de una revisión concreta de la API cuando sea necesario (por ejemplo, 1.0-preview.1, 1.0-preview.2).
  • Una vez publicada una API (1.0, por ejemplo), su versión preliminar (1.0-preview) está en desuso y se puede desactivar después de 12 semanas.
  • Durante este tiempo, debe actualizar a la versión publicada de la API. Una vez desactivada una API en versión preliminar, se rechazan las solicitudes que especifican una -preview versión.

Uso

La versión de la API se puede especificar en el encabezado de la solicitud HTTP o como parámetro de consulta de dirección URL:

Encabezado de solicitud HTTP:

Accept: application/json;api-version=1.0

Uri:

[scheme"://"][host[':'port]]"/v" major-version '/'namespace '/'resource ('/'resource)* '?' query

i.e. GET https://dev.azure.com/v1.0/{organization}/_apis/{area}/{resource}?some-query=1000

Versiones compatibles

Producto 1.0 2.0 3.0 4.0 5.0 6,0 7.0
Azure DevOps Services X x x X x x x
Azure DevOps Server 2022 X X x X x X x
Azure DevOps Server 2020 x X x x x x -
Azure DevOps Server 2019 x x x X x -
Team Foundation Server 2018 X x x X - -
Team Foundation Server 2017 X x X - - -
Team Foundation Server 2015 x x - - - -

Las versiones principales de la versión de API se alinean con las versiones RTM de Team Foundation Server. Por ejemplo, el 3.0 conjunto de API se introdujo con Team Foundation Server 2017.

Algunas API no documentadas de la versión 1.0 existían en Team Foundation Server 2013, pero no se admiten.