Versionamento de APIs RESTful

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.

Usaremos o exemplo daquela primeira API de gastronomia que tínhamos criado no primeiro artigo: https://api.minhagastronomia.com

Se você não leu os primeiros artigos da série, dá uma lida:

• [1] A anatomia de uma API RESTful
• [2] O que você precisa saber sobre métodos e códigos de status do protocolo HTTP
• [3] Segurança em APIs RESTFul

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

Espero que tenham gostado. Agora, você pode dar sequência ao próximo artigo da série: Paginação, Ordenação e Filtros em APIs RESTful.

‍