Como Evitar Alterações Disruptivas na API com o API Gateway
September 11, 2023
Ao desenvolver APIs, você às vezes faz alterações que podem causar problemas para os consumidores atuais da API. Evoluir sua API sem afetar os usuários atuais é essencial, caso contrário, eles podem perder a confiança na sua oferta. É impossível evitar completamente esses problemas, mas você pode minimizar o impacto ou detectar algumas mudanças críticas antes que elas aconteçam. Mudanças que quebram a API precisam ser identificadas durante a fase de desenvolvimento, e, se ocorrerem, o API gateway deve lidar com elas para garantir que os aplicativos clientes permaneçam inalterados. Neste artigo, exploraremos algumas práticas recomendadas e estratégias para prevenir mudanças que quebram a API e como lidar com elas usando o APISIX API Gateway.
O que são mudanças que quebram a API?
Produtos de software evoluem constantemente, e suas APIs não são exceção. Essas APIs servem como a interface principal pela qual os consumidores externos interagem com o seu sistema, refletindo qualquer mudança no produto. Existem várias razões para essas modificações na API, incluindo melhorias tecnológicas, mudanças na direção do negócio, correções de bugs críticos e mais. Em termos simples, uma mudança que quebra a API ocorre quando você altera sua API e isso pode causar problemas para os aplicativos clientes que a utilizam. Algumas dessas mudanças são mais fáceis de identificar do que outras. Aqui estão alguns exemplos de mudanças que quebram a API:
- Remover um Endpoint: Se você tem um endpoint
GET /userse decide removê-lo, qualquer cliente que tentar acessá-lo receberá erros. - Alterar a URL de um Endpoint: Se você mudar a URL de um endpoint de
GET /usersparaGET /members, qualquer cliente usando a URL antiga enfrentará problemas. - Modificar o Payload da Requisição: Se um endpoint espera dados específicos na requisição, como
POST /usersesperando{ "name": "John" }, mas você altera o requisito para{ "firstName": "John" }, isso interromperá os clientes que enviam o formato antigo. - Remover ou Renomear Campos na Resposta: Se os clientes esperam campos específicos na resposta da API, remover ou renomeá-los fará com que esses clientes falhem. Por exemplo, mudar
{ "id": 1, "name": "John" }para{ "id": 1, "fullName": "John Doe" }. - Alterar Tipos de Dados: Se um campo da API é esperado como uma string e você o altera para um inteiro ou outro tipo, isso pode quebrar os clientes. Por exemplo, mudar
"age": "25"para"age": 25. - Alterar Mecanismos de Autenticação: Se você mudar de autenticação básica para autenticação baseada em token sem uma transição adequada, os clientes existentes enfrentarão erros de autenticação.
- Introduzir Campos Obrigatórios: Se você tem um endpoint como
POST /usersque aceita campos opcionais e, de repente, torna um desses campos obrigatório, os clientes existentes que não enviam esse campo enfrentarão problemas. - Alterar Formatos de Erro: Se os clientes estão programados para entender formatos de erro específicos, mudar esses formatos pode levar a um tratamento inadequado de erros no lado do cliente.
- Modificar Códigos de Status HTTP: Alterar os códigos de status para certas operações, como retornar um
200 OKem vez de um201 Createdpara a criação de recursos, pode enganar os clientes. - Descontinuar o Suporte para Versões Antigas da API: Se você eliminar o suporte para versões mais antigas sem um período de transição adequado, os clientes que dependem dessas versões mais antigas quebrarão.
Toda mudança na API tem o potencial de quebrar um aplicativo cliente. Se você usar um API Gateway como uma porta de entrada para todas as APIs de backend, o gateway saberá para onde encaminhar a solicitação com base em um conjunto de regras definidas em uma configuração de rota, e é o lugar certo para lidar com mudanças que quebram a API. Vamos ver como podemos usar o APISIX para identificar algumas mudanças na API.
Validação de esquema de requisição e resposta
Definir esquemas rigorosos para suas rotas permite garantir que as estruturas de requisição e resposta sejam como esperado. Use o plugin request-validation para validar as requisições recebidas e o plugin response-rewrite para reescrever a resposta da API com base em certas condições.
Logs
O APISIX suporta vários plugins de log, como http-logger, elasticsearch-logger, file-logger e mais. Configure um logger para armazenar os dados de requisição e resposta da API e analise os logs regularmente para detectar mudanças nos cabeçalhos de requisição/resposta, estruturas de payload ou qualquer outro padrão incomum.
Monitoramento de rotas e upstreams
Monitore as rotas que passam pelo gateway. Se uma rota anteriormente disponível de repente começar a retornar erros 404, é um sinal potencial de que a API sofreu uma mudança ou um endpoint foi descontinuado. Ative o recurso de verificação de saúde da API para monitorar continuamente a saúde geral dos nós upstream. Se um dos nós começar a falhar, respondendo mais rápido ou mais devagar que o normal, isso pode indicar uma mudança no processamento do serviço backend subjacente. Integre o APISIX com ferramentas de monitoramento como Prometheus usando o plugin prometheus. Configure alertas com base em métricas, como uma taxa aumentada de erros 4xx ou 5xx, que podem indicar mudanças que quebram sua API.
Use versionamento
Versionamento de API é a prática de gerenciar mudanças em uma API e garantir que essas mudanças sejam feitas sem interromper os aplicativos consumidores da API. Existem vários métodos para configurar o versionamento com o APISIX, como usar caminhos de URI, parâmetros de consulta, cabeçalhos ou escolher o tipo de conteúdo. Por exemplo, você pode ter endereços web como /v1/users ou /v2/users para mostrar a versão da sua API. Ao ter essas versões, você pode oferecer mais de uma opção da sua API, permitindo que os consumidores decidam quando atualizar para a versão mais recente no seu próprio ritmo. O APISIX pode facilmente redirecionar todo o tráfego de volta para a versão antiga e estável da API até que você resolva os problemas na nova versão, tornando suas APIs compatíveis com versões anteriores. Use o APISIX para manter a compatibilidade antiga enquanto implementa as novas mudanças; se você detectar problemas na nova versão, o plugin traffic-split permite um rollback rápido.
Avisos de descontinuação
Antes de remover ou alterar recursos, marque-os como descontinuados, dando aos consumidores tempo suficiente para se adaptar. Com a ajuda do APISIX, podemos configurar a rota para comunicar sobre sua futura descontinuação e sua substituição. Para isso, o APISIX oferece o plugin response-rewrite.
Integração com controle de versão
Embora você possa desejar que os revisores de pull requests identifiquem quaisquer mudanças que quebram a API, confiar apenas nesse método não é garantido e pode levar a falhas eventualmente. Se você tiver documentação OpenAPI/Swagger para suas APIs, elas podem ser controladas por versão e incluídas em um pipeline de CI. O APISIX não suporta nativamente a integração direta com sistemas de controle de versão como o Git para mudanças na especificação da API. No entanto, você pode configurar um processo fora do APISIX. Ferramentas como Oasdiff ou Bump podem identificar mudanças nas especificações da API e acionar um pipeline de CI (adicione GitHub Action) que executa testes contra os endpoints da rota no APISIX para garantir que nenhuma mudança que quebre a API seja introduzida.
Outras formas de detectar mudanças
Postman contém um modelo para verificar automaticamente a versão atual da sua API em busca de mudanças que quebram a API e descreve como ele funciona neste artigo. Você adiciona o detector ao pipeline de CI como uma etapa extra. Toda vez que seu pipeline for executado, o detector de mudanças que quebram a API analisará a especificação atual da API em relação à anterior e notificará você sobre quaisquer diferenças. Dependendo da sua stack de desenvolvimento, existem outras bibliotecas para comparar especificações OpenAPI. Este artigo explica bem como capturá-las na prática usando estratégias de implantação testadas antes de levar novas mudanças para produção.
Resumo
Detectar e prevenir mudanças que quebram a API é importante para manter a confiança com os consumidores da API e garantir o sucesso do seu serviço. Ao integrar as capacidades do APISIX, como validação de requisição, versionamento, logs, monitoramento e alertas, com técnicas como testes automatizados de contrato de API, você pode garantir que suas APIs evoluam sem afetar negativamente seus clientes.