Confira as melhores práticas de versionamento de API

Se você já ouviu falar de versionamento de API, sabe que essa é uma prática comum no mercado de softwares. Mas, embora “versionar” possa ser um verbo corriqueiro para muitos desenvolvedores, ele pode ser uma língua diferente para quem não atua na área.

A questão é que ter uma boa estratégia é parte crucial para alcançar os resultados esperados, além da análise de riscos e custos ao implementar qualquer mudança. Sem isso, você pode causar impactos negativos e até perder clientes.

Que tal ficar por dentro disso tudo? Aproveite para descobrir dicas estratégicas de versionamento de API!

O que é versionamento de API?

O versionamento de API é o processo de gerenciar e controlar diferentes versões de uma interface de programação de aplicativos (API).

Mas, para entender o processo, vale relembrar o que é uma API. A sigla vem do inglês Application Programming Interface e significa interface de programação de aplicações. É o que permite que dois sistemas se comuniquem a partir de uma aplicação que os conecta.

Quer um exemplo simples? Quando o seu smartphone oferece a previsão de tempo, ela se baseia em dados de outro software. Já o versionamento de API acontece quando é preciso implementar mudanças. Ou seja, versionar quer dizer mudar determinada estrutura, de acordo com o objetivo que se tem em mente.

Como toda API é feita a partir de um contrato (chamado de swagger), o versionamento também pode ser uma quebra de contrato. Isso pode variar, porque algumas pessoas e empresas consideram quebra apenas quando são inseridos novos campos ou fluxos obrigatórios no sistema. Outras consideram que qualquer modificação é uma quebra de contrato.

Vale saber também que é possível ter dois tipos de versionamento. O chamado “padrão major” é o versionamento externo, que ocorre quando removemos um atributo existente, adicionamos um novo parâmetro obrigatório ou retiramos um media type existente. Já o “padrão minor”, ou versionamento interno, é usado para adicionar um novo recurso à API ou um atributo que não seja obrigatório.

Para que serve?

O versionamento é necessário em qualquer caso de alteração da API. Portanto, pode servir para remover atributos do sistema ou adicionar novidades. Algumas vezes, essas mudanças serão obrigatórias e, em outras, elas podem ser implementadas para que a API tenha um melhor desempenho ou mais funcionalidades.

Uma aplicação prática de API bastante comum acontece no Instagram. Com uma nova interface conectada ao seu perfil na rede social, é possível automatizar processos e conseguir uma atuação mais estratégica nesse canal. Outro exemplo é a automação integrada ao WhatsApp Business.

É também o que acontece com o uso de ferramentas de chatbot para atendimento ao cliente, coleta e análise de dados, além de outros recursos disponibilizados por soluções como o CRM Inteligente da HubSpot. Seguindo o conceito de IPaaS, cria-se um ecossistema central para facilitar as operações no dia a dia.

Quais os tipos de versionamento de APIs?

URI Path
Accept Header
Custom HTTP Header
Subdomínio
Query Parameter

Quem atua na área de programação sabe que uma mudança desse tipo pode acontecer de diferentes maneiras. Reunimos aqui algumas informações sobre os principais tipos de versionamento para você conhecer!

1. URI Path

É a forma mais comum e simples de versionamento. Basta informar a versão na URI (Uniform Resource Identifier, ou Identificador Uniforme de Recursos) para fazer a requisição.

2. Accept Header

Aqui, o versionamento é feito usando o header “accept”, o que também deixa a URI mais limpa.

3. Custom HTTP Header

Assim como no modelo anterior, o versionamento é feito via header, só que de forma customizada no back-end.

4. Subdomíni

O versionamento feito através do subdomínio é geralmente usado para oferecer versões diferentes da API para serviços distintos.

5. Query Parameter

Esse tipo é conhecido por uma maior complexidade ao trabalhar no roteamento de versões.

Como funciona e quais as melhores práticas?

Tenha um plano de ação
Não se esqueça de comunicar
Determine prazos
Mapeie os eventuais problemas
Limite o número de APIs no ar

As mudanças podem ser optativas ou necessárias, mas ainda dá para explorar um pouco mais sobre como funciona o versionamento de API. A seguir, temos dicas relevantes que ajudam você a entender melhor como funciona e as principais práticas!

1. Tenha um plano de ação

Sendo inevitável ou opcional, é importante identificar os consumidores que serão impactados com a transformação a ser implementada. Mapear o impacto vai ajudar que todo o processo seja bem-sucedido, inclusive porque ele deve ser comunicado para todos os envolvidos.

2. Não se esqueça de comunicar

Essa também é uma etapa relevante: a comunicação. Procure informar as pessoas via e-mail, notificação na plataforma ou qualquer outro meio, desde que elas estejam cientes do que está acontecendo ou prestes a acontecer. Alterações não comunicadas podem gerar muitos transtornos.

3. Determine prazos

Trabalhe na definição de um prazo para que o versionamento ocorra, considerando o que vai ser implementado. Algumas mudanças levam dias, meses ou até anos. Ou seja, pode variar bastante, e isso significa que não se pode deixar esse “detalhe” passar despercebido.

4. Mapeie os eventuais problemas

Outra prática crucial quando se fala de versionamento de API é pensar nas possíveis complicações que a mudança pode causar. Por exemplo, caso surja alguma incompatibilidade que não permita usar a nova versão, os usuários devem conseguir retornar para o modelo anterior.

Tudo isso precisa ser planejado para os problemas serem controlados da melhor forma, sem gerar grandes prejuízos. Em outras palavras, vale ter um plano B para cada chance de erro e, mais uma vez, cuidar da comunicação de todo o processo.

5. Limite o número de APIs no ar

Por último, uma dica que não pode ser esquecida: tenha, no máximo, duas versões de API no ar. A ideia de ter muitas opções talvez pareça boa, mas, na verdade, não é indicado se quiser preservar a governança e segurança do sistema. Evitar esse tipo de vulnerabilidade é um cuidado importante a ser tomado.

Como lidar com as mudanças de forma estratégica?

Ainda temos algumas sugestões finais para lidar com o versionamento de APIs. Afinal de contas, essa é uma tarefa que merece atenção, e listamos aqui prioridades para aumentar suas chances de sucesso:

mantenha tudo registrado e atualizado, criando uma documentação sobre a estrutura da API e eventuais mudanças;
pense na segurança do sistema, considerando a possibilidade de ataques aos dados e outros problemas que prejudiquem o desempenho da sua API, optando sempre por tecnologias e plataformas confiáveis;
não encare o versionamento de forma negativa, pois sistemas engessados e que não permitem mudanças podem ser muito ruins. Quando eles são dimensionáveis e ajustados periodicamente, acabam evoluindo e entregando resultados cada vez melhores.

O versionamento de APIs é uma prática muito comum e, muitas vezes, necessária para alcançar os resultados desejados no seu sistema. Por isso, é bom ficar sempre por dentro do que há de novo na área para aplicar tudo na sua estratégia.

Então, aproveite para baixar gratuitamente o Guia de Como Usar API com outras dicas imperdíveis sobre o assunto!