Endpoints em lote e relatório de falhas parciais

O que é

Um endpoint em lote recebe vários itens numa única requisição: criar 500 contatos, atualizar 50 preços ou, como no JSON batching do Microsoft Graph (citado), agrupar até 20 subrequisições arbitrárias numa só chamada HTTP. Existem dois comportamentos. Atômico: todos os itens são aplicados ou nenhum. Sucesso parcial: o servidor aplica o que for possível e reporta cada falha. A AIP-233 do Google (citada) exige que um batch create síncrono seja atômico, e a justificativa explica o motivo: um status OK implica que tudo funcionou, de modo que acrescentar depois informações de falha parcial a uma resposta síncrona mudaria silenciosamente o que os clientes existentes presumem. Lotes assíncronos, que devolvem uma operação, podem suportar sucesso parcial e reportar as falhas como um mapa do índice da requisição para um objeto de status; erros transitórios que o servidor vai tentar de novo não devem aparecer ali, e, quando todos os itens falham, a própria operação é marcada como falha.

Por que importa

Os clientes repetem requisições em lote. Com semântica atômica, repetir é seguro; com sucesso parcial, a repetição reenvia itens já aplicados, a menos que o cliente consiga saber quais falharam. O formato do relatório determina se as repetições criam duplicatas.

Como aplicar

• Escolha um comportamento por endpoint, documente-o e nunca o altere no endpoint existente; passar de atômico para sucesso parcial exige uma nova versão ou um flag explícito cujo padrão seja o comportamento antigo (a AIP-233 descreve return_partial_success).
• Reporte o status no nível da requisição separadamente dos resultados por item. O Graph devolve 200 para qualquer lote que possa ser interpretado, dá a cada subresposta o seu próprio status e afirma que um 200 no lote não indica que as requisições individuais tiveram sucesso.
• Identifique as falhas pelo índice ou por um id fornecido pelo cliente que seja único dentro do lote, e reutilize o formato de erro de item único para que os fluxos de código do cliente sejam compartilhados.
• Limite o tamanho do lote e declare esse limite. Aplique autorização, validação e limites de taxa por item; o Graph avalia cada requisição individualmente quanto ao throttling e faz essa requisição falhar com 429.
• Suporte ordenação apenas quando for necessário; o dependsOn do Graph faz os dependentes falharem com 424 (Failed Dependency) quando um pré-requisito falha.
• O 207 (Multi-Status) do WebDAV (RFC 4918, citada) existe para múltiplos status por recurso, mas clientes e proxies genéricos não o conhecem; um corpo JSON com status por item é mais portável.

Armadilhas

Um endpoint de sucesso parcial que devolve um simples 200 e enterra as falhas num log. Devolver o conteúdo das requisições nas entradas de erro, o que a AIP-233 rejeitou por razões de sensibilidade dos dados. Lotes cujo processamento excede o timeout do gateway: a partir de certo tamanho, o trabalho em lote pertence a uma operação de longa duração.