[Gov.Doc API] Implementar versionamento

A. Introdução

Para facilitar novas implementações e alterações no Gov.Doc API, propõem-se implementar versionamento na API, pois é um padrão utilizado em todo o mundo nas APIs,APIs independenteindependentemente das tecnologias utilizadas. Assim sendo, analisou-se as possibilidades de implementação, identificou-se as possíveis alterações necessárias, os impactos e levantou-se as demandas necessárias para atender ao objetivo de minimizar o impacto de novas alterações nosna API, assim, não afetando sistemas que atualmente integram com a API.mesma.

1. O que é versionamento

ParaÉ melhoro gerenciarprocesso ade complexidadeatribuir eum mudançasnome significativasúnico que ocorre em sua API, crieou uma versãnumeração única para indicar o estado da sua API. É como o screenshot do que foi entregue até aquele ponto. O controle de versão (versionamento) da API facilitaFacilita a identificação de erros e permite alterações significativas, minimizando o impacto nas integrações com sua API. 

• Alguns benefícios:
  • • Permite ter um mecanismo simples que facilite a implementação de conceitos de DEVOPS, como CI (Continous Integrations) e CD (Continuous Delivery).
    • A abordagem preferida de utilização da versão é a de URL via PATH pois é pode ser responsável pela estabilidade estrutural da API, e por pacotes maiores de atualização.1

2. Quando implementar

Se é uma API que possui várias integrações ou se tem grande impacto nos sistemas que integram com ela, é de grande valia implementar o versionamento. O mesmo, permite que ao longo das alterações que a API sofre, você possa gradualmente descontinuando funcionalidades e permitindo que novas implementações não impactem integrações existentes com a API. O melhor momento para implementação é na criação da API.

Foi identificado a necessidade de implementar o versionamento devido aos seguintes cenários:

• "Já se deparou com uma situação terrível de ter desenvolvido um sistema que consome algum tipo de API, e ele parar de funcionar, pois o serviço que o sistema consumia foi atualizado? Ou também em uma outra ótica para quem desenvolve as APIs, aquela discussão árdua para atualiza-la, criando até comitês de inúmeras pessoas (clientes), discutindo horas somente para atualizar um atributo que é necessário para uma situação (cliente) e para outro não faz sentido a alteração?". 

3. ComoOpções implementarde implementação

Há três possíveis implementações:

• URL, versão por Path

  • Exemplo: https://api-v1.minhagastronomia/vinhos ou https://api.minhagastronomia/v2/products/product-namev1/vinhos
    
  • Prós e Contras

    • Prós	Contras
      1. É a opção mais utilizada do mercado	1. Adiciona comprimento à sua rota
      2. É muito mais claro e simplessimples. Além de sedar identificarum visual mais clean na URL, facilita a versão, permitindo que navegação usuáriopara consulteoutras versões da API. É mais dev-friendly comparado a documentaçãooutras corretaabordagens.
      3. Muitos frameworks oferecem suporte à esse versionamento
      4. Você pode facilmente estruturar sua API para permitir o versionamento por rota

• Accept headers, o header customizado

  • Exemplo: Accept-Version: v2
  • Prós e Contras

    • Prós	Contras
      1. UmaA reflexãpriori, uma solução tardia
      2. O servidor pode responder apropriadamente com os dados de resposta corretos.fácil.	1. Obriga a informar cabeçalhos personalizados
      3.2. ASe priori,formos umaseguir soluça especificação fácil.ao pé da letra, essa é a maneira correta de fazer o versionamento de APIs.	2. Não é dev-friendly, pois a requisição tem que ser feita com muito mais cuidado.
      3. É que sua URL permanece clean e intacta.

• Query string, passar por parâmetro na URL
  

  • Exemplo: /products/product-name?version=v2
  • Prós e Contras

    • Prós	Contras
      1. É mais uma gambiarra doabordagem que umajá realfoi solução.muito utilizada.	1. Caiu em desuso. É conhecida como má prática por muitos desenvolvedores.
      	2. Além de prejudicar a navegação para outras versões, a legibilidade da URL fica ruim em cenários de muitos parâmetros na query string

4. ImpactosImplementando

HáAlgumas ainda novas actionspossibilidades e controllerssugestões de implementação levantadas.

• Pode se implementar utilizando os pacotes disponíveis: WebApi.Versioning e Mvc.Versioning. 
  

• 	Código
  Para uma implementação super fácil (com ASP.NET Core)
  Já possui uma API mas não possui versionamento
  Quando há 3 versões mas somente 2 controllers, é possível implementar mais de uma versão por controller.
  Para descontinuar o uso de uma versão no endpoint.

• Status HTTP a serem criadas.implementados:

  • 301 - Moved permanently

    • Indica que o endpoint com a URI solicitada foi movida permanentemente para outra URI.
    • Pode ser usado para indicar o uso de uma versão de API obsoleta / sem suporte.

  • 302 - Not found

5. Alterações necessárias 

Há ainda novas actions e controllers a serem criadas.

6. Demandas necessárias 

Há ainda novas actions e controllers a serem criadas.

B. Conclusão

Concluímos que essas alterações necessárias para aplicar o padrão RESTful. O projeto ainda é passível de outras melhorias na arquitetura, nomenclatura de classes, métodos e variáveis, melhorias nos testes unitários e nos testes de integração. 

 

Fontes

1. "As melhores práticas para controle de versões em APIs REST", Neilton Rocha.
   
2. "Versionando APIs RESTful", Thiago Lima.
3. "ASP.NET Core RESTful Web API versioning made easy", Scott Hanselman.
4. "A importância do versionamento de APIs", Patrick Francis Gomes Rocha.