O padrão Long-running Operations (LRO) em Web APIs refere-se a operações que não podem fornecer uma resposta imediata devido à sua natureza demorada.
Essas operações podem ser complexas ou envolver um grande volume de processamento, tornando inviável uma resposta síncrona. Aqui estão os detalhes deste padrão com base no conhecimento disponível:
O que São Long-running Operations
- Operações Assíncronas: LROs são operações que ocorrem de forma assíncrona. Em vez de o cliente esperar pela conclusão da operação, o servidor inicia o trabalho e retorna um objeto de status (placeholder) que representa essa operação em andamento.
- Rastreamento de Progresso: O cliente pode usar esse objeto de status para verificar periodicamente o progresso da operação ou obter o resultado quando a operação for concluída.
Como Devem Ser Usados
- Início da Operação: Quando uma LRO é iniciada, o servidor retorna imediatamente um identificador único ou um recurso de status para a operação.
- Verificação de Status: O cliente usa esse identificador para consultar o status da operação, que pode incluir informações como percentual de conclusão, sucesso ou falha, e dados do resultado (se disponíveis).
- Ações Adicionais: Dependendo da API, o cliente pode ter a opção de pausar, retomar ou cancelar a operação usando métodos específicos fornecidos pela API.
Exemplo Prático
Imagine uma Web API para processamento de vídeo. Um cliente envia um vídeo para ser transcrito e legendado, o que pode levar algum tempo.
- Envio do Vídeo: O cliente faz uma requisição POST com o vídeo. A API inicia o processo e retorna um identificador de operação.
- Checagem de Status: O cliente periodicamente faz requisições GET usando o identificador para verificar o progresso. A API responde com o status atual, como “em processamento” ou “concluído”.
- Resultado Final: Uma vez que a operação é concluída, a requisição de status retorna um link para baixar o vídeo transcrito e legendado.
Considerações de Design e Implementação
- Escalabilidade e Performance: LROs são essenciais para operações que podem sobrecarregar o servidor ou levar muito tempo para serem concluídas, garantindo que a API permaneça responsiva e escalável.
- Feedback ao Usuário: Forneça feedback claro e atualizações de status para manter o usuário informado sobre o progresso da operação.
- Documentação e Testes: Documente as LROs cuidadosamente, incluindo como iniciar operações, verificar o status e lidar com resultados. Teste exaustivamente para garantir a confiabilidade.
Em resumo, Long-running Operations são uma abordagem vital para lidar com processamentos demorados ou complexos em Web APIs, permitindo que as operações sejam executadas de forma assíncrona enquanto fornecem ao cliente a capacidade de monitorar e controlar essas operações.
É possível usar custom methods para operações de pausa ou cancelamento em operações longas (Long-running Operations) em Web APIs. Essas operações permitem ao cliente ter mais controle sobre o processamento assíncrono, como pausar temporariamente uma operação ou cancelá-la completamente. Vamos ver exemplos de como essas chamadas seriam estruturadas:
Exemplo de Chamada para Pausar uma Operação
Suponha que temos uma operação longa em execução com um identificador 12345. Para pausar essa operação, poderíamos usar um custom method como segue:
POST /longRunningOperations/12345:pause HTTP/1.1
Host: api.example.com
Neste exemplo, estamos fazendo uma solicitação POST para a URL que representa a operação longa específica (12345). O segmento :pause indica que estamos chamando o custom method para pausar a operação.
Exemplo de Chamada para Cancelar uma Operação
Para cancelar uma operação longa, o processo é semelhante. Continuando com o mesmo identificador de operação 12345, a chamada para cancelar seria:
POST /longRunningOperations/12345:cancel HTTP/1.1
Host: api.example.com
Aqui, a solicitação POST direcionada para o mesmo endpoint da operação longa usa o segmento :cancel para indicar que desejamos cancelar a operação.
Considerações Adicionais
- Feedback ao Cliente: Após uma chamada para pausar ou cancelar, a API deve retornar uma confirmação de que a ação foi realizada com sucesso ou informar sobre qualquer erro.
- Estado da Operação: O cliente deve ser capaz de verificar o estado atual da operação (por exemplo, pausada, em andamento, cancelada) através de solicitações de status regulares.
- Idempotência: Idealmente, as chamadas para pausar ou cancelar devem ser idempotentes, ou seja, chamadas repetidas devem ter o mesmo efeito que uma única chamada.
Esses custom methods proporcionam flexibilidade adicional no gerenciamento de operações assíncronas em Web APIs, permitindo interações mais dinâmicas entre o cliente e o servidor.