Sabe aquela situação horrível de ter desenvolvido um aplicativo, e ele parar de funcionar, pois alguém atualizou a versão da API que você consumia?
É exatamente sobre esse assunto “desagradável” que vamos falar hoje…
Se você desenvolve ou quer desenvolver APIs, a solução desse problema é simples, e se chama “versionamento”.
Existem diversas maneiras de versionar sua API, e nesse artigo vou listar as principais formas.
Agora, vamos lá aprender sobre os tipos de versionamentos em APIs.
Versionamento pela URL
Quando versionamos pela URL temos três maneiras de fazer isso: subdomínio, path ou query string.
No modelo de subdomínio você especifica a versão logo no início da URL, por exemplo:
HTTP GET
https://api-v1.minhagastronomia/vinhos
Notem que logo após o api, eu coloquei o “-v1”, que específica a versão, e nesse caso quem for consumir pode alterar apenas o subdomínio na requisição.
No modelo de path você especifica a versão após a base url, por exemplo:
HTTP GET
https://api.minhagastronomia/v1/vinhos
Essa é uma das abordagens mais utilizadas, pois além de dar um visual mais clean na URL, facilita a navegação para outras versões da API, ou seja, é mais dev-friendly comparado a outras abordagens.
Tem quem é mais criativo, e prefere especificar a versão via query string, por exemplo:
HTTP GET
https://api.minhagastronomia/vinhos?version=1.0&pais=brasil
Notem que na URL eu coloquei o parâmetro via query string “version” e especifiquei a versão 1.0 da API.
Essa é uma abordagem que já foi muito utilizada, mas que caiu em desuso, pois 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.
Versionamento pelo Header
O versionamento via header pode ser via HTTP content-type, ou seja, utilizando o header “Accept” na requisição, como por exemplo:
HTTP GET
https://api.minhagastronomia/vinhos
Accept: application/vnd.gastronomia.v2+json
Se formos seguir a especificação ao pé da letra, essa é a maneira correta de fazer o versionamento de APIs.
Também existe a abordagem de utilização de um header customizado para especificar a versão, como por exemplo:
HTTP GET
https://api.minhagastronomia.com/vinhos
api-version: 2
Note, acima, que nesse caso eu criei um novo header chamado “api-version” para que o consumidor especifique a versão desejada na requisição.
O ponto positivo é que sua URL permanece clean e intacta, o ponto negativo é que não é dev-friendly, pois a requisição tem que ser feita com muito mais cuidado.
Boas práticas
Versionamento é uma das maiores discussões ao redor da comunidade de APIs, pois a própria especificação não cria uma boa experiência ao developer.
Por isso, minha recomendação é seguir o melhor das duas abordagens com foco em proporcionar uma ótima experiência ao desenvolvedor que irá consumir a API, ou seja, o versionamento não pode influenciar negativamente na jornada do consumir.
Por outro lado, o criador da API também deve conseguir ter um mecanismo simples que facilite a implementação de conceitos de DEVOPS, como CI (Continous Integrations) e CD (Continuous Delivery).
Nesse sentido, gosto da abordagem de utilização da versão na URL via PATH para ser responsável pela estabilidade estrutural da API, e por pacotes maiores de atualização.
Acrescentando também um header customizado que serve para espeficificar a data da sub-versão, e é o responsável por atualizações menores, como: campos do metadado, parâmetros da Query String, e coisas do tipo.
Nessa abordagem, a requisição ficaria da seguinte forma:
HTTP GET
https://api.minhagastronomia.com/v1/vinhos
api-version: “2019-06-01”
Quem utiliza essa abordagem muito bem é o Stripe.
Conclusão sobre versionamento de APIs RESTful
Como eu disse, não existe mundo perfeito quando falamos de versionamento em APIs, é uma discussão que muitas vezes vai pelo gosto pessoal do desenvolvedor, então o melhor a se fazer é entender bem o cenário, e implementar a abordagem que faz mais sentido!
E se quiser menos “dor de cabeça” nessa implementação, escolha um API Management para te ajudar.
