Ir para o conteúdo principal

[Gov.Doc API] Implementar versionamento

Data de elaboração05/12/2022
Responsável pelo estudo

Nara Carolina Galvão Feitosa

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

Equipe do estudoTambakiss
AlvoGov.Doc API
Origem

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

ObjetivoCom 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, independente das tecnologias utilizadas. Assim sendo, analisou-se as possibilidades de implementação, identificou-se as 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 nos sistemas que atualmente integram com a API.


1. O que é versionamento

Para melhor gerenciar a complexidade e mudanças significativas que ocorre em sua API, crie uma versão da sua API. É como o screenshot do que foi entregue até aquele ponto. O controle de versão (versionamento) da API facilita a identificação de erros e permite alterações significativas, minimizando o impacto nas integrações com sua API. 

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.

3. Como implementar 

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

  • URL, versão por Path
    • Exemplo: /v2/products/product-name
    • Prós e Contras
      • PrósContras
        1. É a opção mais utilizada do mercado1. Adiciona comprimento à sua rota 
        2. É muito mais claro e simples de se identificar a versão, permitindo que o usuário consulte a documentação correta
        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ósContras
        1. Uma reflexão tardia
        2. O servidor pode responder apropriadamente com os dados de resposta corretos.1. Obriga a informar cabeçalhos personalizados 
        3. A priori, uma solução fácil.
  • Query string, passar por parâmetro na URL
    • Exemplo: /products/product-name?version=v2
    • Prós e Contras
      • PrósContras
        1. É mais uma gambiarra do que uma real solução. É conhecida como má prática por muitos desenvolvedores.


4. Impactos

Há ainda novas actions e controllers a serem criadas.


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.