[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 independentemente das tecnologias utilizadas. Assim sendo, objetivo desse estudo é analisar as possibilidades de implementação, identificar as possíveis alterações e levantar as demandas necessárias.

1. O que é versionamento

É o processo de atribuir um nome único ou uma numeração única para indicar o estado da API. Facilita 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ções.

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. Opções de implementação

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

• URL, versão por Path

  • Exemplo: https://api-v1.minhagastronomia/vinhos ou https://api.minhagastronomia/v1/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 simples. Além de dar um visual mais clean na URL, facilita a navegação para outras versões da API. É mais dev-friendly comparado a outras abordagens.
      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. A priori, uma solução fácil.	1. Obriga a informar cabeçalhos personalizados
      2. Se formos seguir a especificação 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. É uma abordagem que já foi 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. Implementando

Algumas possibilidades e sugestõ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)
  Para quando 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.
  Implementar status 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.

5. Alterações necessárias 

A sugestão é criar uma nova controller com versionamento, levar os endpoints do Gov.Doc (somente utilizados por ele) para ela, criar uma padronização para atuais/futuros projetos (como é elaborada o número da versão, como será a organização de endpoint e os retornos - HTTP status code) e por fim, montar um calendário para descontinuar controller não versionada.

• Criar pasta dentro de Controllers para cada versão.
• Para cada controller:
  • Criar nova controller dentro da pasta /Controller/v2 com a mesma nomenclatura.
  • Mover controller antiga para dentro da pasta /Controller/v1.
  • Adicionar [ApiVersion("2")] e [Route("v{version:apiVersion}/[controller]")] na nova controller 
  • Mover endpoints utilizados pelos Gov.Doc (frontend) para a versão 2.
• Criar pasta dentro de Services e Dtos para cada versão
• Elaborar calendário com datas:
  • Para subir versão 2.0 para development, staging e production
  • Para descontinuar endpoints sem versão

B. Conclusão

Concluímos que essas são alterações necessárias para implementar o versionamento e que irá agregar grande valor para as APIs que aplicarem. Permitirá entregas mais fluídas e de menor impacto.

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.