[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, 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ós	Contras
      1. É a opção mais utilizada do mercado	1. 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ós	Contras
      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ós	Contras
      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.