¶ [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) | ![[gov.doc_api]_implementar_versionamento.png](/banco_de_imagens/code/estudos_dos_times/%5Bgov.doc_api%5D_implementar_versionamento.png) |
| Para quando possui uma API mas não possui versionamento | ![[gov.doc_api]_implementar_versionamento2.png](/banco_de_imagens/code/estudos_dos_times/%5Bgov.doc_api%5D_implementar_versionamento2.png) |
| Quando há 3 versões mas somente 2 controllers, é possível implementar mais de uma versão por controller. | ![[gov.doc_api]_implementar_versionamento3.png](/banco_de_imagens/code/estudos_dos_times/%5Bgov.doc_api%5D_implementar_versionamento3.png) |
| Para descontinuar o uso de uma versão no endpoint. | ![[gov.doc_api]_implementar_versionamento4.png](/banco_de_imagens/code/estudos_dos_times/%5Bgov.doc_api%5D_implementar_versionamento4.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. |
![[gov.doc_api]_implementar_versionamento5.png](/banco_de_imagens/code/estudos_dos_times/%5Bgov.doc_api%5D_implementar_versionamento5.png)
¶ 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
- «As melhores práticas para controle de versões em APIs REST», Neilton Rocha.
- «Versionando APIs RESTful», Thiago Lima.
- «ASP.NET Core RESTful Web API versioning made easy», Scott Hanselman.
- «A importância do versionamento de APIs», Patrick Francis Gomes Rocha.