Os webservices já são uma unanimidade na forma de comunicação entre diferentes tipos de serviços, muito populares e indispensáveis em qualquer integração. O fato é que: é questão de tempo até que a API do seu projeto necessite conter melhorias.
Muito já se falou em como projetar a melhor arquitetura de uma API. Entretanto, percebe-se a necessidade de melhorias já que muita coisa mudou, como, por exemplo, a popularização dos micro-serviços.
O primeiro desafio é saber qual diretriz seguir: realizar as melhorias contínuas na API ou começar a desenvolver uma nova versão?
As melhorias continuas
A atualização contínua da API usando a mesma versão é um caso que necessita ser bastante pensado, pois ao adotar esta saída se encontrará muitas adversidades pelo caminho.
Características:
- Funciona como se a aplicação estivesse sempre na versão v1;
- Impede a inclusão de novos atributos obrigatórios;
- Impede a retirada de atributos;
- Tende a deixar os endpoints mais complexos;
- Ao longo do tempo pode tornar-se insustentável.
Por hora, vamos abandonar essa diretriz e partir para o versionamento.
Versionamento da API
Adotando-se que uma boa API é versionada, e que o objetivo dela é ser usada por clientes além do seu controle, é fundamental a compatibilidade sempre que possível. Quando existir a necessidade de alguma quebra de contrato, devido a novas funcionalidades, uma nova versão deve ser gerada. Use baixa granularidade (v1,v2,v3, etc..)
Desafios:
- Compatibilidade – O contrato entre cliente e API é fundamental e realizar modificações nos endpoints sem quebra de contrato é a prioridade zero. A compatibilidade deve ser preservada a todo momento.
- Documentação atualizada – Manter uma documentação atualizada é vital para o uso de qualquer API. A documentação é especificação do produto. Uma má documentação gera mais chamados para a equipe de suporte e, fatalmente, gera mais custo para a empresa.
- Forçar o cliente a migrar – De alguma maneira, o cliente deve ser forçado, em um determinado período, a migrar para as versões mais recentes – para que a API não contenha muitas versões ativas.
- Planejar e validar – É recomendável não criar muitas versões. Deve ser planejado de forma que, cada versão, contenha o máximo de atualizações. Algumas APIs famosas postergam por meses para serem atualizadas para a próxima versão.
Técnicas de como versionar uma API
Aqui nesse ponto temos muitas divergências na comunidade. O que pode ser boa prática para uns, é inadmissível para outros engenheiros de software. Sem tomar partido, vamos exemplificar as possibilidades existentes.
As técnicas mais comuns são:
URI – Como as URL’s não fazem parte do contrato, elas podem sofrer alterações, então, podemos versionar nossa API adicionando o número da versão na URL.
http://api.yebo/api/customers/1234
http://api.yebo/api/v3.0/customers/1234 http://api.yebo/api/v3/customers/1234
Características:
- Viola regra do HATEOAS;
- Fácil roteamento entre servidores;
- Fácil manutenção do código;
- Não requer utilização de cabeçalhos;
QUERY STRING – O parâmetro da versão é passado via parâmetro query string na URL da chamada de forma muito simples.
http://api.yebo/api/customers/1234?version=1.1
http://api.yebo/api/customers/1234?version=2.2
http://api.yebo/api/customers/1234?version=3.4
Características:
- Viola regra do HATEOAS;
- Difícil manutenção do código;
- Não requer utilização de cabeçalhos;
HEADERS – Outro método adotado é adicionar o número da versão nos cabeçalhos das requisições HTTP usando o cabeçalho Accept, de forma que, através do cabeçalho, seja possível realizar de forma condicional o uso da versão desejada.
// Através de um parâmetro Accept: application/json; version=v1 // Através de um vendor content type Accept: application/vnd.yebo.api-v1+json
Características:
- De acordo com regra do HATEOAS;
- Dificulta a implementação de clientes;
- Difícil manutenção do código;
URI + HEADERS – Por fim, recentemente encontramos algumas APIs que adotam a mistura de dois métodos (URI e HEADERS) de uma forma muito interessante: a URI segue mantendo o número da versão principal e, dentro de cada versão principal, utiliza-se o cabeçalho Accept como versão secundária para responder as versões menores em conformidade. Em cenários onde a API sofre constante melhorias, esta técnica pode funcionar perfeitamente.
$ curl http://api.yebo/v1/customers \ -u merchantID: xxx \ -H "Yebo-Version: 2016-01-01"
Características:
- Viola regra do HATEOAS;
- Fácil manutenção do código;
- Requer utilização de cabeçalhos;
- Flexibilidade para o cliente;
Conclusão
Independente da técnica de versionamento a ser utilizada, analise e planeje com precaução os impactos que pode causar para o cliente. Outro fato importante é que, de alguma maneira, acarretará um impacto na complexidade governança e um aumento de custos de operação e desenvolvimento.