API para aplicativo: modele estados e falhas de envio

O desafio de API para aplicativo

Quando a resposta não chega, o aplicativo pode não saber se a operação falhou ou se o servidor concluiu e a conexão caiu depois. Repetir o envio sem regra pode duplicar registros. O contrato da API precisa permitir reconhecer a operação e consultar seu estado, além de documentar o formato dos campos.

Como organizar contrato de dados

Descreva entradas, saídas, estados e condições de erro a partir das tarefas do produto. Defina a identidade de operações que possam ser repetidas e a forma de recuperar sua situação. O comportamento deve ser coerente entre cliente e servidor, sem depender apenas de bloquear o botão na interface.

1. Defina o que caracteriza uma operação e como seu identificador acompanha tentativas repetidas.
2. Documente respostas de validação, indisponibilidade e autorização com ações esperadas do aplicativo.
3. Teste a perda de conexão depois do processamento e antes de o cliente receber a confirmação.

O contrato deve distinguir erros corrigíveis pela pessoa de condições que pedem nova tentativa posterior. Um campo obrigatório ausente exige revisar a entrada; indisponibilidade temporária pede outro comportamento. As respostas também precisam considerar a autorização sem expor dados indevidos. Documente quais mensagens são voltadas à interface e quais referências permitem localizar o diagnóstico no serviço. A consistência entre esses níveis evita que detalhes técnicos sejam exibidos como instruções que o usuário não consegue executar.

Exemplo aplicado: repetição de operação

Exemplo hipotético: um app envia uma solicitação de retirada com identificador próprio. O serviço conclui o registro, mas a resposta se perde. Na retomada, o aplicativo consulta ou repete a operação conforme o contrato e recebe o mesmo resultado, sem criar outra solicitação para o mesmo evento.

Desabilitar o botão evita alguns toques repetidos, mas não trata retomadas automáticas, reabertura do app ou falhas entre o processamento e a resposta.

A identidade da operação deve permanecer estável quando a transmissão é repetida pelo mesmo motivo. Gere e preserve a referência conforme o contrato definido, inclusive se o processo do aplicativo for interrompido. Se a pessoa iniciar uma nova solicitação legítima, ela precisa ser reconhecida como outra intenção. Essa distinção não pode depender apenas de igualdade de campos: dois pedidos iguais podem ser desejados, enquanto uma retransmissão do mesmo pedido não representa necessariamente outra compra.

Critérios para resposta do servidor

A profundidade do contrato deve acompanhar o impacto da operação. Consultas simples e alterações com consequências diferentes precisam de comportamentos específicos, incluindo autorização e validação no serviço.

Retornar a mesma mensagem para qualquer falha impede recuperação adequada. Outro problema é incluir no aplicativo uma chave que concede acesso amplo ao serviço, como se o cliente fosse um ambiente confiável.

Mantenha exemplos de resposta para sucesso, validação recusada, acesso negado e confirmação incerta. Use-os para revisar os estados da interface e os testes de integração. Mudanças no formato do serviço devem considerar clientes já distribuídos que continuarão enviando solicitações antigas. Registre a política de compatibilidade e evite remover campos sem avaliar esse uso. Um contrato bem definido inclui como a API evolui, além de mostrar o que ela aceita na primeira versão do aplicativo.

Acompanhamento de integração mobile

Acompanhe operações sem confirmação, duplicidades, respostas inesperadas e tempo até resolução. Correlacione os registros por identificador para reconstruir o percurso sem coletar conteúdo sensível desnecessário.

Escolha uma ação de criação, documente seu tratamento de repetição e execute um teste em que o servidor conclui antes de a conexão ser interrompida.