Ir para o conteúdo principal

[Gov.Doc API] Implementar versionamento

Data de elaboração 12/01/2023
Responsável pelo estudo

Nara Carolina Galvão Feitosa

Raissa de Sousa Stodulski
Taillon Miguel Gonçalves
Ádelle Camarão Monteiro

Equipe do estudo Tambakiss
Alvo Gov.Doc API
Origem

Implementação, para facilitar alterações na API sem afetar sistemas que integram atualmente com o projeto

Objetivo Com o versionamento, facilitar novas implementações na API pois estará minimizando os impactos nos sistemas que já integram com API.
Documentação correlata (opcional)
Observações


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)


    image.png

    Para quando possui uma API mas não possui versionamento  

    image.png

    Quando há 3 versões mas somente 2 controllers, é possível implementar mais de uma versão por controller.


    image.png

    Para descontinuar o uso de uma versão no endpoint.


    image.png

    image.png

    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.