Versionamento dos endpoints

Isso é uma questão extremamente importante… como lidar com a evolução da interface pública e as breaking changes?

Num módulo gerenciado pelo NPM isso é super fácil, a gestão pelo lado de quem consome isso já vem de graça por conta de como o NPM lida com semantic versioning… agora, como fazer numa rota pública que inclusive não pode ter versionamento gerenciado por uma conta/perfil como é feito em casos como Pagar.me e Stripe, dado que não teremos esse conceito de conta?

[kevenleone]

Opa @filipedeschamps , eu acho sim legal a estratégia do semantic version, porém na minha visão de usuário fica difícil memorizar qual versão específica que ele usou e deu certo, e qual que ele deveria utilizar, porque ai teríamos seguindo sua ideia:

1.0.0, 1.0.1, 1.0.2 e por ai em diante, a ideia de se utilizar v1, v2, v3 (ou até mesmo 1, 2, 3, porém pode parecer fora de contexto usar números soltos) seria para utilizar uma versão consolidada (sempre a mais recente) de uma versão específica.

O nosso querido GitHub também possui suas apis V3, V4, sei que não da pra se utilizar bem como base, porque as APIS possuem arquiteturas diferentes, a V3 para Rest e V4 para GraphQL (n sei se tem Rest também). Porém até onde vi não utilizam esse versionamento na URL, mas é devolvido um Header com essa informação da versão que ele está usando, que poderia ser útil para aprimorar nossa ideia aqui

E ao final, poderíamos ter uma lib genérica brasilapi como a AWS faz com seus endpoints, por exemplo. O que acha?

Isso aqui eu acho sensacional, facilitaria muito para centralizar essas interfaces.

Então só pra finalizar, sobre o semantic versioning eu acho bom, porém acredito que em um certo momento pode ser mais difícil controlar e manter do que apenas uma versão consolidada (v1,v2…)

É isso, muito bom trocar ideia sobre isso com você, seria bom também sugestões de outras pessoas para melhorar aqui a discussão ! 🚀

[kevenleone]

Hey @filipedeschamps ,

Sobre o versionamento poderia ser criado um novo parâmetro na API do cep-promise com options para informar qual API ele quer acessar (por default sempre a mais recente), por exemplo:

import getCEP from 'cep-promise';
const cep = 12345678
const options = {
  version: 'v1'
};

getCEP(cep, options)

E na interface do BrasilAPI aceitar um Header com a versão que quer acessar, assim:

Header  {
  version: 'v1'
};

Ou, na interface também poderia versionar por meio de rotas, atualmente se usa:

{{URL}}/api/cep/12345678

e poderia ser {{URL}}/api/v1/cep/12345678.

Acredito que ajustes precisariam ser feitos na estrutura do cep-promise para suportar um versionamento funcional, para não descartar a forma que era feita anteriormente.

Deu pra compreender a ideia??