Uma das coisas mais legais do TFS 2015 é a introdução da API REST. Como quase tudo que envolve o TFS e o VSTS, o desenvolvimento dessa API é incremental.

Porém, desenvolvimento incremental de serviços introduz dois problemas: Como evoluir a API sem quebrar clientes antigos? E em qual versão do produto foi introduzida uma certa API?

A resposta a ambas as perguntas é a mesma: o modelo de versionamento da API REST do TFS.

A documentação da API REST do TFS pode ser encontrada no site do Visual Studio. Lá, na página de introdução, há uma dica importante:

Tip: To avoid having your app or service broken as APIs evolve, specify an API version on every request.

A página com a documentação da versão da API, mencionada no link acima, indica:

  • Como incluir o número de versão numa chamada à API; e
  • Qual a versão mais recente de cada uma das APIs.

Essas informações são muito importantes para resolver o primeiro dos problemas que mencionei no início deste post; entretanto, não resolvem o segundo problema. Então agora vou te contar como saber quando uma certa API foi introduzida. O segredo está no número da versão.

O número da versão da API

A versão da API informa quando ela foi introduzida. O esquema de versionamento, por sua vez, é alinhado com as releases do TFS. Assim:

Versão da API

  • 2.0: TFS 2015 RTM
  • 2.1: TFS 2015 Update 1
  • 2.2: TFS 2015 Update 2
  • 2.3: TFS 2015 Update 3
  • 3.0: TFS v.next (TFS “15”)

A lista acima indica a versão inicial em que uma API foi introduzida. Assim, como exemplo, uma API marcada com a versão 2.0 estará disponível a partir do TFS 2015 RTM. Vale lembrar que todas as APIs estão disponíveis no VSTS, independentemente de versão.

Ah, em tempo: Muitas das APIs estão documentadas como “1.0”,  o que significa que elas foram introduzidas antes do TFS 2015 RTM. Por isso, com apenas algumas poucas exceções (Build APIs), todas as APIs com versão 1.0 estão disponíveis no TFS 2015 e posteriores.

Um abraço,
Igor

(Agradecimento especial a Will Smythe, da Microsoft, por ter compilado a lista de versões da API)

(Cross-post de http://www.tshooter.com.br/2016/05/25/entenda-o-versionamento-da-api-rest-do-tfs/)

tags

ExtensibilityREST APITFSVSTS

Igor Abade

Igor Abade V. Leite ([email protected]) é Microsoft MVP (Most Valuable Professional) de Visual Studio ALM desde 2006. Palestrante em diversos eventos da comunidade de desenvolvimento de software (TechEd Brasil, The Developers’ Conference, DevOps Summit Brasil, Agile Brazil, Visual Studio Summit, QCON e outros), é também autor de artigos em revistas e sites como o MSDN Brasil. Desde março de 2011 é um dos sócios da Lambda3, uma consultoria especializada em ALM, desenvolvimento de software e treinamentos. Siga-o no Twitter @igorabade.