HTTP 202 aceito (HTTP / 1.1)
Você está procurando HTTP 202 Accepted
status. Veja RFC 2616 :
A solicitação foi aceita para processamento, mas o processamento não foi concluído.
Processamento HTTP 102 (WebDAV)
A RFC 2518 sugere o uso de HTTP 102 Processing
:
O código de status 102 (Processamento) é uma resposta provisória usada para informar o cliente que o servidor aceitou a solicitação completa, mas ainda não a concluiu.
mas tem uma ressalva:
O servidor DEVE enviar uma resposta final após a solicitação ter sido concluída.
Não sei como interpretar a última frase. O servidor deve evitar enviar algo durante o processamento e responder somente após a conclusão? Ou apenas força o encerramento da resposta somente quando o processamento termina? Isso pode ser útil se você deseja relatar o progresso. Envie HTTP 102 e libere resposta byte a byte (ou linha por linha).
Por exemplo, para um processo longo mas linear, você pode enviar cem pontos, liberando após cada caractere. Se o lado do cliente (como um aplicativo JavaScript) souber que deve esperar exatamente 100 caracteres, poderá combiná-lo com uma barra de progresso para mostrar ao usuário.
Outro exemplo diz respeito a um processo que consiste em várias etapas não lineares. Após cada etapa, você pode liberar uma mensagem de log que eventualmente será exibida ao usuário, para que o usuário final saiba como está o processo.
Problemas com descarga progressiva
Observe que, embora essa técnica tenha seus méritos, eu não a recomendaria . Uma das razões é que força a conexão a permanecer aberta, o que pode prejudicar em termos de disponibilidade do serviço e não é bem dimensionado.
Uma abordagem melhor é responder HTTP 202 Accepted
e permitir que o usuário retorne mais tarde para determinar se o processamento terminou (por exemplo, chamando repetidamente um determinado URI, como o /process/result
que responderia com o HTTP 404 Not Found ou o HTTP 409 Conflict até o processo termina e o resultado está pronto) ou notifique o usuário quando o processamento estiver concluído, se você puder chamar o cliente de volta, por exemplo, por meio de um serviço de fila de mensagens ( exemplo ) ou WebSockets.
Exemplo prático
Imagine um serviço da web que converte vídeos. O ponto de entrada é:
POST /video/convert
que pega um arquivo de vídeo da solicitação HTTP e faz alguma mágica com ele. Vamos imaginar que a mágica consome muita CPU, portanto não pode ser feita em tempo real durante a transferência da solicitação. Isso significa que, depois que o arquivo for transferido, o servidor responderá com um HTTP 202 Accepted
conteúdo JSON, o que significa “Sim, peguei o seu vídeo e estou trabalhando nele; estará pronto em algum lugar no futuro e estará disponível através do ID 123. "
O cliente tem a possibilidade de se inscrever em uma fila de mensagens para ser notificado quando o processamento terminar. Quando terminar, o cliente pode baixar o vídeo processado, acessando:
GET /video/download/123
o que leva a um HTTP 200
.
O que acontece se o cliente consultar esse URI antes de receber a notificação? Bem, o servidor responderá uma HTTP 404
vez que, de fato, o vídeo ainda não existe. Pode estar preparado atualmente. Pode nunca ter sido solicitado. Pode existir algum tempo no passado e ser removido mais tarde. Tudo o que importa é que o vídeo resultante não esteja disponível.
Agora, e se o cliente se importar não apenas com o vídeo final, mas também com o progresso (o que seria ainda mais importante se não houver serviço de fila de mensagens ou mecanismo semelhante)?
Nesse caso, você pode usar outro ponto de extremidade:
GET /video/status/123
o que resultaria em uma resposta semelhante a esta:
HTTP 200
{
"id": 123,
"status": "queued",
"priority": 2,
"progress-percent": 0,
"submitted-utc-time": "2016-04-19T13:59:22"
}
Fazer a solicitação repetidamente mostrará o progresso até que seja:
HTTP 200
{
"id": 123,
"status": "done",
"progress-percent": 100,
"submitted-utc-time": "2016-04-19T13:59:22"
}
É crucial fazer a diferença entre esses três tipos de solicitações:
POST /video/convert
enfileira uma tarefa. Deve ser chamado apenas uma vez: chamá-lo novamente colocaria em fila uma tarefa adicional.
GET /video/download/123
diz respeito ao resultado da operação: o recurso é o vídeo. O processamento - foi o que aconteceu sob o capô para preparar o resultado real antes da solicitação e independentemente da solicitação - é irrelevante aqui. Pode ser chamado uma vez ou várias vezes.
GET /video/status/123
diz respeito ao processamento em si . Não enfileira nada. Não se importa com o vídeo resultante. O recurso é o próprio processamento. Pode ser chamado uma vez ou várias vezes.