APIs e Microsserviços

30 set, 2016

Os desafios da manutenção de uma API Restful

Publicidade

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.