Defina a operação de VPN antes de comparar APIs

Uma página de produto diz que tem uma API, e a reunião de integração trava na segunda pergunta. Qual operação, sobre qual objeto, chamada por quem, e o que conta como sucesso? Responder a essas quatro antes de comparar produtos costuma eliminar metade dos candidatos. Também transforma a comparação restante em algo que um teste pode resolver.

Substitua «tem uma API» por uma operação

Uma API é um transporte, não uma capacidade. Um endpoint REST, um socket local e um invólucro de linha de comando podem todos ser chamados de API, e não oferecem operações equivalentes.

Escreva a operação como uma frase antes de olhar a documentação.

Iniciar uma conexão local é ação do lado do cliente com um usuário à frente. Emitir um perfil de dispositivo é uma ação de provisionamento com um inventário por trás. Desativar o acesso de um usuário é uma ação administrativa com trilha de auditoria. Essas três costumam morar em componentes diferentes, de equipes diferentes, com autoridades diferentes.

Quatro campos que tornam o contrato testável

Preencha quatro campos para cada operação: o objeto, a ação, o chamador e a condição de sucesso. Um contrato com campo faltando é um desejo.

A tabela é a planilha inteira:

A condição de sucesso é o campo que as pessoas pulam, e é ela que decide se a integração funciona. Uma configuração salva não é um túnel ativo, e uma conta desativada não é uma sessão encerrada.

Se duas operações precisam de chamadores diferentes, são duas integrações. Juntá-las em uma única conta de serviço costuma significar conceder mais autoridade do que qualquer uma delas precisa.

Combine a interface com a camada a que ela realmente pertence

A interface de gerenciamento da comunidade do OpenVPN conversa com um daemon por TCP ou um socket Unix. Seus comandos incluem observações de estado e sinais ao daemon.

Isso a torna um canal de controle do daemon, não uma API de assinatura hospedada nem um serviço de registro de usuários. Ler a documentação com atenção evita construir sobre uma camada que não é dona do objeto.

Essa documentação também diz que o protocolo não traz criptografia própria. Quem alcança o socket pode controlar o daemon, então trate-o como controle sensível, não como um feed de métricas. Prenda-o ao loopback ou a um socket Unix, e coloque-o atrás de um arranjo restrito se um chamador remoto precisar. Expô-lo à internet por conveniência transforma um canal de controle em incidente.

Especifique o comportamento após a chamada

Aceitação não é o mesmo que conclusão. O daemon pode retornar antes de o túnel subir, então espere o evento documentado de conclusão ou falha e amarre-o à requisição que você enviou.

Decida o que o chamador faz se a resposta se perder. Repetir cegamente uma criação ou uma reconexão não é o mesmo que verificar se a primeira requisição já fez efeito.

Remover acesso é pelo menos três ações diferentes: bloquear o próximo login, encerrar uma sessão ativa e revogar a credencial. Peça as que a política realmente exige, e diga no contrato qual é qual. Não rotule uma atualização de conta bem-sucedida como revogação completa sem evidência. A diferença importa durante um incidente, quando o relógio corre.

Verifique o contrato com um piloto

Um pequeno piloto aprovado deve cobrir sucesso, rejeição, interrupção e nova tentativa, seguido pela operação da aplicação que deve ser permitida ou negada.

Para uma interface no nível do daemon, dois comandos exercitam a observação e um sinal:

echo state | nc -w 2 127.0.0.1 7505
echo signal SIGTERM | nc -w 2 127.0.0.1 7505

Conceda apenas a autoridade que a operação exige. Mantenha segredos fora de logs de rotina, e registre detalhe privado suficiente para dizer qual alvo foi afetado e como terminou.

Anote o caminho de recuperação para o caso de a própria API de controle estar fora. Escolha a interface que é dona do objeto e de seu ciclo de vida; alegações de automação numa página de produto não substituem isso.