APIs e integrações

O que esta categoria cobre

Quatro trabalhos relacionados ficam aqui. Criar e testar requisições à mão. Documentar uma interface para que outras pessoas possam usá-la. Colocar um gateway na frente de vários serviços para que chaves, limites, cotas e versões se comportem do mesmo jeito em todo lugar. Mover dados entre produtos que nunca foram projetados para conversar.

Os três primeiros são para equipes que entregam uma API. O quarto é para quem costura ferramentas que comprou. Os dois públicos acabam nesta prateleira, e por isso os produtos são tão diferentes entre si.

A automação puramente visual, sem código, pertence a no-code e automação. Alertas sobre um serviço em produção são monitoramento.

Clientes e o que os diferencia hoje

Todo cliente envia uma requisição e mostra uma resposta. As diferenças estão mais adiante.

O tratamento de ambientes vem primeiro: local, homologação, produção e o que um colega rodar no notebook, alternando sem esforço e sem ninguém editar uma URL à mão. Depois os scripts, para que um token seja obtido antes da requisição em vez de colado toda manhã. Depois as asserções de teste, para que uma coleção se torne algo que um servidor de build consiga executar.

A colaboração é onde as opiniões se dividem. A sincronização na nuvem é prática e coloca o histórico das suas requisições nos servidores de outra empresa. As ferramentas baseadas em arquivos guardam as coleções no repositório, ao lado do código, de modo que uma mudança é revisada como qualquer outra e nenhum workspace sai da empresa junto com um funcionário que se desliga.

Pergunte onde ficam os segredos em qualquer dos casos. Uma chave gravada numa coleção exportada é o caminho clássico para um repositório público.

Documentação que não apodrece

A documentação escrita à mão fica desatualizada em um trimestre. O único arranjo que sobrevive é a geração a partir de uma especificação que vive com o código e é reconstruída quando o código entra por merge.

Confira três coisas: se o produto lê o formato da sua especificação sem uma etapa de conversão, se os exemplos podem ser executados a partir da página e se as versões antigas continuam publicadas para quem ainda as usa.

Um changelog importa mais que o design. Quem consome precisa saber o que quebrou e quando, e nenhum acabamento visual substitui isso.

Gateways e quando vale a pena ter um

Um único serviço raramente precisa de um gateway. O caso aparece quando autenticação, limites de requisições, cotas e versionamento precisam se comportar de modo idêntico em vários serviços.

Nesse ponto as perguntas são: onde ele roda e quanta latência acrescenta, como os limites são definidos, o que quem chama vê quando um deles é atingido, se as chaves podem ser trocadas sem indisponibilidade e o que os logs contêm. Tudo o que termina tráfego vira um risco de disponibilidade por si só, então pergunte o que acontece quando o próprio gateway tem um dia ruim.

O que o preço mede

• Usuários nos clientes e nos produtos de documentação, às vezes gratuitos para revisores somente leitura.
• Tarefas ou execuções nas plataformas de integração, contadas por etapa e não por fluxo.
• Chamadas ou largura de banda nos gateways, com uma tarifa à parte para o que vem do cache.
• Retenção do histórico de execuções, que é curta nos planos de entrada e curta justamente quando você precisa dela.
• Conectores, com os premium reservados a um plano acima do que está sendo cotado.

O preço por tarefa merece uma conta antes da assinatura. Um fluxo com seis etapas rodando a cada dez minutos não é uma tarefa por mês, e o número em que ele se transforma já surpreendeu muitas equipes. O mesmo tipo de surpresa em outras categorias está reunido em o que as páginas de preços escondem.

O que testar

Reconstrua de ponta a ponta uma integração real que você já roda, incluindo a parte em que o outro lado devolve um erro.

Observe como a ferramenta lida com novas tentativas, entrega duplicada, um terceiro que trava e um payload que chega com um campo faltando. Os produtos bem feitos permitem reproduzir uma execução com falha depois de corrigida a causa. Os mais fracos a perdem em silêncio e não avisam nada até que um cliente avise.

Depois confira a saída. Coleções, especificações e definições de fluxo devem poder ser exportadas como arquivos legíveis. Tudo o que fica trancado dentro de um workspace é trabalho que você fará duas vezes.

Documentação, versionamento e como manter quem consome

Uma interface com usuários é uma promessa, e a maior parte da dificuldade desta categoria vem de mudar uma sem quebrar essa promessa.

Decida uma abordagem de versionamento antes de o primeiro consumidor externo chegar, porque adaptá-la depois significa pedir a todos que mudem ao mesmo tempo. Seja qual for o esquema, publique o que mudou e quando, e dê um prazo de descontinuação medido em meses, não em semanas.

Os erros merecem tanta atenção quanto os acertos. Uma resposta que diz o que deu errado, qual campo causou o problema e o que fazer em seguida elimina mais chamados de suporte do que qualquer quantidade de texto.

Depois leia a sua própria documentação como um recém-chegado leria. A melhoria mais rápida costuma ser um exemplo funcionando no topo da página, em vez de uma tabela de referência.