Versionamento de APIs: entenda o que é e quais as boas práticas de mercado

Você sabe o que é versionamento de APIs e quais as boas práticas levando em consideração segurança, governança e experiência do desenvolvedor? Nesse artigo traremos a definição deste conceito e quais as formas de versionamento e as melhores práticas de mercado.

É o ciclo natural, tudo muda, e não é diferente para as APIs. APIs exemplares e altamente utilizadas também passam por mudanças, é inevitável. Porém, mesmo sendo inevitável não quer dizer que seja legal, pois mudanças geram impactos, custos, e se a estratégia de versionamento não for bem feita pode gerar impactos no negócio, como perda de clientes ou parceiros. Por isso, é de extrema importância entender o que é versionamento de APIs, quais os tipos, como estruturar uma estratégia e as boas práticas em tudo que envolve mudanças nas APIs.

O que é versionamento de APIs

É o processo de implementação de mudanças em uma determinada API. Quando realizamos alterações que modificam a estrutura daquela API, devemos versioná-la. Utilizamos o versionamento semântico para controle das versões.

Por boas práticas, o padrão major (ex: v1) em exposição para os consumidores e padrão minor (ex: v1.2) para mudanças internas que não causem quebra de contrato.

As APIs são consumidas a partir de um contrato (swagger), definido pelo OpenAPI Specification. Sendo assim, toda alteração feita neste contrato pode quebrar as integrações que estão consumindo a API. Por isso, quando fazemos alterações em sua estrutura, estamos quebrando esse contrato (e possivelmente as integrações).

A concepção do que é ou não uma quebra de contrato varia de organização para organização. Para algumas empresas, o contrato só é quebrado quando são inseridos novos campos obrigatórios ou quando é inserido algum fluxo de autenticação/autorização.

Outras empresas, porém, entendem que a quebra de contrato independe da obrigatoriedade. Então, se um novo parâmetro é inserido no body de uma requisição POST, mesmo não sendo obrigatório, o contrato foi modificado, gerando assim a quebra (mesmo que não necessariamente na integração).

Na maioria dos casos, utilizamos o versionamento externo (padrão major) quando:

• removemos um atributo existente;
• adicionamos um novo parâmetro obrigatório;
• ou retiramos um media type existente;

Para versionamentos internos (padrão minor):

• quando adicionamos um novo recurso na API;
• ou um atributo que não seja obrigatório.

O primeiro passo para garantir uma estratégia de versionamento adequada é saber quando versionar. Tendo definido esse conceito na organização, também é necessário definir qual tipo de versionamento será utilizado.

Quais os tipos de versionamento

URI Path

É a forma mais comum de versionamento de APIs. Neste tipo, a versão é informada na URI (Uniform Resource Identifier, ou Identificador Uniforme de Recursos) da requisição. Sendo bem fácil de configurar e simples de entender.

Accept Header

Neste cenário, o versionamento é feito via header, deixando a URI mais limpa. É bastante utilizado em cenários de negociação de conteúdo, onde conseguimos trabalhar com representação única por recurso.

Custom HTTP Header

Assim como no Accept Header, neste tipo de versionamento também trabalhamos a versão via header, mas de forma customizada. Ou seja, no backend é desenvolvido uma forma customizada de trabalhar com a versão da API. Os cenários de uso também se aplicam ao do accept header, a diferença é que nesse tipo é customizado, gerando mais flexibilidade.

Query Parameter

Assim como o versionamento via URI path, o tipo via Query Parameter também é fácil de configurar, mas pode ser um pouco mais difícil para trabalhar no roteamento de versões.

‍Subdomínio

O versionamento feito através do subdomínio geralmente envolve tipos de serviço (backend) diferentes. Onde podemos ter versões diferentes para serviços diferentes. Por exemplo, v1 para um webservice, e v2 para um microsserviço.

5 passos para uma boa estratégia de versionamento de APIs

Agora que sabemos o que é e quais os tipos de versionamento de APIs, podemos falar sobre a estratégia para versionar. Afinal, você não pretende só virar a chave de Vx para Vy, certo?

O primeiro passo da estratégia de versionamento é definir se ela precisa mesmo versionar a API (#brinks… ou não!). Entendendo que o versionamento é inevitável, o próximo passo é identificar os consumidores que serão impactados pela mudança. Você tem conhecimento de todos os desenvolvedores/aplicações que utilizam suas APIs, certo?

Identificando esses consumidores, o segundo passo é trabalhar na comunicação. Será feita via e-mail? Via portal de desenvolvedores? Como e por quais meios acontecerá?

A terceiro passo é determinar o prazo para adequação. Esse prazo vai depender de diversos fatores como o tipo de API, o tipo e quantidade de consumidores, o tipo de mudança que está sendo realizada… Algumas empresas colocam o prazo de 6 meses, outras de 2 anos… Realmente vai depender muito!

O quarto passo é refletir sobre possíveis problemas que podem acontecer ao versionar essa API. A melhor forma de trabalhar no versionamento é que exista compatibilidade com versões anteriores. Caso aconteça algum problema, o consumidor conseguirá facilmente voltar para a versão anterior sem muito impacto.

E o quinto e último passo, que na verdade é mais uma recomendação, é: TENHA O MÁXIMO DE 2 VERSÕES DA API NO AR!

Sabemos que na teoria, geralmente, é fácil, mas na prática nem sempre funciona como gostaríamos. Porém, tenha sempre em mente que quanto menos versões da API no ar, menor será a possibilidade de impacto negativo em sua governança e, consequentemente, em sua segurança. Vale ressaltar que falhas relacionadas a governança estão entre as vulnerabilidades mais comuns em APIs de acordo com OWASP Top 10 API Security.

Conclusão

É importante salientar que em tecnologia, dificilmente haverá uma “bala de prata”, e com o versionamento de APIs não é diferente. Não existe o melhor tipo ou a melhor estratégia. Sempre dependerá das políticas internas da organização, caso de uso, tipos de consumidores, tipo de API etc. Mas mesmo não existindo “bala de prata”, existem várias práticas de mercado que utilizamos e que vocês puderam conhecer.

‍