Versionamento dos endpoints about brasilapi HOT 13 CLOSED

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 ! 🚀

from brasilapi.

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??

from brasilapi.

Olá pessoal!

Eu achei super interessante a discussão dessa thread, é justamente um assunto que já venho estudando há alguns dias atrás.

Vasculhando por artigos que pudessem me entregar informações úteis eu me deparei com um do Thiago Lima CEO da LinkApi.

Fiquem tranquilos isso não é nenhum merchan kkkkk, mas se tratando de API's eles são uma baita referência, então pra sustentar a tese do nosso amigo @kevenleone que deixou bem claro uma maneira incrível de fazer esse versionamento segue esse link com o artigo do Thiago. 😃

from brasilapi.

ele vai precisar atualizar a aplicação dele manualmente sempre que a API mudar pra ter os fixes mais recentes

Se, ainda assim, forem usar versão completa na URL, da pra fazer o parse da versão como o npm por exemplo, onde o MINOR e PATCH são opcionais, isso iria solucionar o problema pro pessoal não precisar atualizar a URL manualmente pra ter as correções.

Por exemplo, as versões 1, 1.0, 1.0.0 seriam aceitas, quando um campo não for especificado o fallback será o mais recente.

Mas ainda acho v1, v2, vN mais eficiente.

from brasilapi.

Que discussão fantástica! E parabéns a todos por embarcarem numa versão tão crua desse repositório! É o estágio mais legal do projeto na minha opinião 👍

Então acho que temos uma conclusão sobre a URL pelo menos (o resto podemos ir incrementando aos poucos).

Vamos então de:

https://brasilapi.com.br/api/cep/v1/[numero]

Alguém aqui encara fazer essa alteração bastante estrutural e histórica para o repositório? Eu sei fazer essa alteração, mas não adicionaria a ninguém eu fazer ela. @lucianopf você também está proibido 😂

Quem topa? 👍

PS: desculpa a demora em responder, o YouTube ta consumindo o tempo de um full time job real, mas ta bem massa 😍

from brasilapi.

Ola pessoal,
Estava vendo sobre o versionamento , minha visão como usuário concordo com o que o @kevenleone comentou, por ser mais facil memorizar assim como a do Github e o google Maps
https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY.

from brasilapi.

Hum 🤔

O artigo do @walefe é super interessante.

E se utilizarmos como é falado sobre o Stripe? Ficaria assim:

A Major ficaria na url:
{{URL}}/api/cep/v1/{{CEP}}

A Minor e Patch ficariam no header:

HTTP GET
https://brasilapi.com.br/api/cep/v1/02152000
api-version: "1.0.15"

O Stripe no caso retorna a data da última alteração que contém algum incompatibilidade. Ele considera para isso alguns motivos. Podemos fazer algo parecido, se for o caso, mas eu achei bacana a possibilidade do semantic 🤔

HTTP GET
https://brasilapi.com.br/api/cep/v1/02152000
api-version: "2020-02-14"

Eu como desenvolvedor acharia de boa conseguir fazer uma request passando api-version no header

from brasilapi.

Deu total @kevenleone show!!!!

No caso da interface do cep-promise, eu tentaria ao máximo "esmagar" as breanking changes dos providers para tentar manter a mesma interface (como inclusive fazemos hoje com os atuais providers, dado que cada um expõe sua interface de uma forma diferente e nós normalizamos numa única interface). De qualquer forma, como o cep-promise é um módulo npm, eu sugiro fazer o semantic versioning pelo package.json... e fica na lib a responsabilidade de atualizar os endpoints dos providers que ela usa.

Agora sobre a interface do Brasil API, eu gosto da sua segunda sugestão de colocar na rota, pois isso facilita muito consumir o endpoint direto pelo navegador ou por qualquer outro client. Você vê algo contra usar a mesma estratégia do semantic version na URL ao invés de v1, v2? Por exemplo:

/api/cep/1.0.0/05010000

Dois pontos:

1. Assim no histórico dos endpoints você tem a informação se ela é patch, minor ou major (breaking change). Inclusive, pensando melhor, não deveria precisar mudar a URL para patches ou minors, voltando então a sua idéia 😂 mas continuando:
2. Nota que eu coloquei o versionamento depois do /cep porque com isso cada serviço pode ter sua versão.

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

from brasilapi.

Otimo Artigo....

from brasilapi.

Em quais situações reais alguém explicitamente precisaria definir a versão da API que vai ser usada?

De acordo com o semver.org todos os PATCH devem ser só correções, se o usuário precisar definir o PATCH ele vai precisar atualizar a aplicação dele manualmente sempre que a API mudar pra ter os fixes mais recentes. O MINOR até faz sentido poder escolher, mas ele é ou pelo menos deveria ser sempre compatível com a versão anterior, então deixar o usuário escolher só adiciona complexidade desnecessária tanto pro client quanto pra API. Por isso as APIs usam v1, v2, v3, etc, ja que só a MAJOR introduz braking changes.

from brasilapi.

Um ponto interessante pra questionar é, o que será considerado uma breaking change na nossa API, a adição de novos parâmetros, ou de uma nova rota ou apenas alteração na interface de rotas existentes? 🤔

Muito boa a discussão galera! 🚀

Me pergunto se ao invés de versionar apenas os pacotes (como cep ou cnpj) não seria melhor versionar o serviço inteiro da API, pq assim como foi dito adicionaria complexidade para nossos clientes para gerenciar as versões atuais de cada serviço. 🤔

from brasilapi.

Um ponto interessante pra questionar é, o que será considerado uma breaking change na nossa API, a adição de novos parâmetros, ou de uma nova rota ou apenas alteração na interface de rotas existentes?

Só se os parâmetros forem obrigatórios, mudem a resposta da API quando não especificados ou remova campos da resposta que existiam antes. Adicionar novas rotas não é breaking change.
Basicamente, se for usado TDD e quebrar algum dos testes é breaking change

from brasilapi.

@mukaschultze fez a implementação no PR https://github.com/filipedeschamps/BrasilAPI/pull/25

Turma vocês são demais!!!!!! 🤝

E aproveitando, @CarlosZiegler o vídeo da semana que vem possivelmente é sobre um link que você compartilhou lá no passado 👍 Esse aqui: https://free-for.dev lembra?

Abração!!!

from brasilapi.