Antes de criar uma integração: avalie a política de alterações da API de uma aplicação

Comece pelas tarefas críticas da integração

Uma integração de API liga duas ou mais aplicações para que possam trocar dados ou funcionalidades. Esta é uma definição geral, não uma garantia sobre as capacidades ou políticas de uma aplicação específica ([OpenText, “What Is API Integration?”](https://www.opentext.com/what-is-api-integration)). Antes de comparar políticas de API, defina o que a integração tem de fazer. A importância de uma política é proporcional ao trabalho empresarial que dela depende: uma alteração que afeta um relatório raramente utilizado é diferente de outra que interrompe o processamento de encomendas ou as atualizações de clientes.

Descreva o fluxo de trabalho em termos operacionais, não apenas como uma lista de endpoints. Assim, será mais fácil testar se a interface documentada da aplicação suporta o trabalho de que realmente precisa.

• Registos: Que objetos têm de ser consultados, criados, atualizados ou associados?
• Ações: Que ações de utilizadores ou sistemas têm de acionar a integração?
• Fluxo de trabalho: Qual é a sequência esperada e que etapas têm de ser concluídas em conjunto?
• Impacto de uma falha: O que acontece se um pedido deixar de funcionar, se atrasar ou produzir dados incompletos?
• Responsabilidade: Quem vai manter a ligação e responder quando falhar?

Encontre a política publicada para o ciclo de vida da API

Consulte a documentação oficial da API da aplicação, os guias para programadores, as notas de lançamento, o registo de alterações e os materiais de suporte. Procure declarações explícitas sobre compatibilidade, alterações incompatíveis, descontinuação, retirada, períodos de suporte e formas de anunciar alterações.

Não deduza que existe uma política apenas porque há números de versão ou porque um pedido à API funciona hoje. Um rótulo de versão, por si só, não indica durante quanto tempo uma interface terá suporte nem com quanta antecedência será anunciada uma alteração. Se a documentação não esclarecer o assunto ou for ambígua, registe-o como uma questão por responder, em vez de presumir que a API é estável.

• Existe uma explicação clara do que o fornecedor considera uma alteração incompatível?
• A documentação explica como são identificados os endpoints ou campos descontinuados?
• É indicado algum período de suporte ou transição? Registe o âmbito e a redação exatos, sem generalizar.
• Onde são anunciadas as alterações e a equipa responsável consegue acompanhar esse canal de forma fiável?
• As declarações sobre a política têm data ou estão associadas a produtos e áreas específicas da API?

Verifique as evidências que sustentam a política

Uma política é mais útil quando pode ser relacionada com evidências concretas e atuais. Compare a referência oficial da API com os registos de alterações, exemplos e qualquer processo publicado para comunicar problemas técnicos. Confirme que os materiais abrangem a superfície da API de que o fluxo de trabalho precisa, e não apenas o produto em geral.

Considere os exemplos como ilustrações, não como uma garantia de que todos os comportamentos estão especificados. Se um requisito importante não estiver documentado, faça uma pergunta precisa ao fornecedor ou responsável pela manutenção e guarde a resposta junto da sua avaliação.

• Registe a página da documentação e a data em que a consultou.
• Compare as operações documentadas com a lista dos registos e ações críticos.
• Verifique se os anúncios de alterações explicam o impacto, as interfaces afetadas e as ações eventualmente necessárias.
• Anote lacunas, declarações contraditórias e os pontos que exigem esclarecimento por escrito.
• Pergunte como comunicar problemas técnicos e que informações o suporte ou responsável pela manutenção precisa para os investigar.

Teste o contrato, não apenas um pedido bem-sucedido

Um único pedido bem-sucedido prova apenas que um pedido funcionou numa situação específica. Teste o contrato em que a integração se baseia: o significado e o formato dos identificadores, os campos obrigatórios, as relações, a estrutura das respostas e o comportamento em caso de falha. Use a documentação oficial como referência para o comportamento esperado e registe quaisquer diferenças observadas.

Dê prioridade aos testes das suposições que poderiam causar trabalho incorreto ou perdido se mudassem. Por exemplo, verifique como a integração lida com um campo opcional ausente, uma resposta inesperada, um pedido rejeitado e um registo que não pode ser processado. Não presuma que um campo opcional estará sempre presente nem que uma resposta de erro terá uma estrutura específica, a menos que isso seja confirmado pela documentação ou pelos seus próprios testes.

• Confirme como os registos são identificados e se o fluxo de trabalho depende de um identificador específico.
• Verifique que campos são obrigatórios em cada operação e o que acontece quando os valores são omitidos ou estão vazios.
• Teste os percursos de sucesso e de falha, incluindo a resposta recebida pela integração quando uma operação é rejeitada.
• Teste os casos relevantes para o fluxo de trabalho em que faltam campos, os valores são inesperados ou as respostas diferem da estrutura prevista.
• Guarde pedidos e respostas representativos, bem como os resultados esperados, como testes de regressão, excluindo dados de produção sensíveis.

Descubra como testar alterações em segurança

Pergunte se está disponível uma sandbox, uma instância de teste ou outro ambiente não produtivo e esclareça o que representa na prática. Um ambiente de teste só é útil se permitir à equipa experimentar as operações relevantes e observar um comportamento significativo; não presuma que corresponde ao ambiente de produção nem que recebe as alterações ao mesmo tempo.

Se não houver um ambiente adequado, determine se pode testar com dados não produtivos representativos numa instância controlada. Esclareça como os dados de teste são separados, quem lhes pode aceder e como serão eliminados ou repostos. Se não conseguir testar em segurança um fluxo de trabalho crítico antes de uma alteração chegar à produção, considere isso um risco operacional significativo.

• Pode criar e repor registos de teste sem afetar os fluxos de trabalho em produção?
• O ambiente disponibiliza as operações da API de que a integração precisa?
• Como são comunicadas as alterações ao ambiente de teste e até que ponto este reflete o ambiente em que vai confiar?
• É possível validar a autenticação, as permissões e o tratamento de erros sem usar credenciais de produção ou registos sensíveis?
• Qual é o plano alternativo de testes se o fornecedor não disponibilizar um ambiente não produtivo adequado?

Planeie a manutenção da integração do seu lado

Mesmo uma política bem documentada não elimina a necessidade de manter a integração. Mantenha um registo breve das dependências, indicando a aplicação, as áreas da API, os fluxos de trabalho críticos, os locais da documentação e a pessoa responsável por rever os avisos de alterações.

Implemente uma monitorização que ajude a detetar trabalhos falhados ou incompletos e defina quem os investiga. Sempre que possível, volte a testar as suposições importantes após uma alteração relevante. Se alojar uma aplicação por conta própria, o alojamento e as operações são aspetos distintos da política de ciclo de vida da API da aplicação: a infraestrutura gerida pode tratar de partes da implementação e da gestão do serviço, mas não substitui as suas decisões sobre dados, acesso, comportamento da integração ou revisão de alterações.

• Designe alguém para acompanhar o canal oficial de alterações e encaminhar os avisos para as pessoas certas.
• Documente as dependências da integração e o impacto empresarial de uma falha.
• Monitorize resultados importantes, como execuções falhadas ou registos não processados, usando ferramentas adequadas à sua configuração.
• Mantenha testes para os fluxos de trabalho críticos e volte a executá-los quando o comportamento relevante da API possa ter mudado.
• Defina um plano de resposta: quem investiga, quem comunica o impacto e como interromper ou recuperar o fluxo de trabalho.

Compare as opções com uma grelha de decisão

Use as mesmas perguntas para cada aplicação, para que um site de documentação bem apresentado não faça esquecer a ausência de respostas sobre o ciclo de vida. Como referência geral para a avaliação de integrações, a Workato apresenta perguntas sobre os tipos de dados e aplicações envolvidos; esse material não especifica políticas de ciclo de vida de API ([Workato, “Evaluating an integration platform?”](https://www.workato.com/the-connector/evaluating-an-integration-platform-heres-what-you-need-to-know/)). Classifique cada item como documentado, testado, confirmado pelo fornecedor, desconhecido ou não aplicável. Estas categorias distinguem evidências de suposições.

Não existe uma pontuação universal que torne uma API uma escolha segura. Defina os seus próprios requisitos mínimos de acordo com o impacto de uma falha, a capacidade de manter a integração e as evidências que consegue obter. Um fluxo de trabalho crítico pode justificar a exigência de respostas explícitas por escrito ou de uma forma segura de testar; uma utilização de baixo impacto pode tolerar mais incerteza.

• Fluxo de trabalho crítico e registos afetados: O que tem de continuar a funcionar?
• Evidências sobre o ciclo de vida: Onde são descritas a compatibilidade, a descontinuação e as notificações de alterações?
• Abrangência: Os materiais oficiais cobrem exatamente as operações e os campos de que precisa?
• Testes: É possível testar em segurança o comportamento crítico antes de depender dele?
• Adequação operacional: A equipa consegue acompanhar os avisos, testar alterações e responder a falhas?
• Questões em aberto: O que tem de ser confirmado pelo fornecedor ou responsável pela manutenção antes da escolha?
• Decisão: A incerteza restante é aceitável para este fluxo de trabalho e que medida de mitigação vai utilizar?

Onde se enquadra o alojamento gerido de aplicações autoalojadas

Para as equipas que escolhem uma aplicação empresarial autoalojada, o alojamento e a adequação da API são decisões relacionadas, mas distintas. A Airbip disponibiliza a implementação gerida de aplicações do seu catálogo público como cargas de trabalho Docker em servidores na cloud da Airbip. O seu serviço automatiza o encaminhamento e os certificados TLS, inclui verificações de DNS, gestão do ciclo de vida do serviço e cópias de segurança diárias, semanais e mensais configuráveis, além de suportar um subdomínio Airbip ou um domínio personalizado compatível.

Estas capacidades de infraestrutura não definem a política de alterações da API de uma aplicação nem garantem que uma determinada integração continue a funcionar. Avalie separadamente a documentação oficial da aplicação e teste os fluxos de trabalho relevantes. Decida também como a equipa vai gerir os dados da aplicação, as credenciais, as permissões e a manutenção da integração. Consulte o site atual da Airbip para obter informações sobre os planos disponíveis e as condições comerciais exatas.