API em Lote (Batch API)

O cliente envia um array de itens, cada um com ID, operação e payload. Um exemplo de iluminação contém 50 comandos de brilho. A resposta devolve `results` correlacionados por ID, com status e erro. O servidor pode processar em paralelo ou série. A ordem de retorno não deve ser presumida. IDs únicos são obrigatórios. O limite de itens, como 100 por lote, protege memória e tempo. O tamanho total, por exemplo 1 MB, também. O contrato precisa definir se um item inválido rejeita apenas ele ou todo o envelope. Para automação, a resposta parcial deve atualizar somente dispositivos confirmados. Um lote aceito não significa que cada atuador executou fisicamente.

APIs do Google Workspace combinam requisições HTTP completas em uma única mensagem `multipart/mixed`. Cada parte contém método, URL, cabeçalhos e corpo; a resposta traz partes com status próprios. Isso preserva semântica de endpoints existentes sem criar um endpoint JSON específico. As subrequisições continuam contando individualmente para quotas. O formato é mais complexo de gerar e analisar. Fronteiras MIME, Content-ID e cabeçalhos precisam estar corretos. A execução pode ser separada pelo servidor. Não assumir ordem de execução. Uma operação dependente da anterior não deve ser colocada no mesmo lote sem mecanismo explícito. O ganho vem de reduzir round trips, não de obter transação.

Algumas APIs oferecem lote atômico: todas as mudanças são aplicadas ou nenhuma. Google Docs `batchUpdate` processa uma lista de requests num documento com regras específicas. Bancos oferecem transações. Esse comportamento precisa ser declarado. Não se deve inferir pelo nome batch. Em casa inteligente, ligar 20 luzes dificilmente é uma transação física: uma pode estar offline. O servidor pode aceitar atomicamente a intenção, mas a execução distribuída continua parcial. Para configurações em banco, atomicidade pode ser real. O contrato deve separar validação, commit e efeitos externos. Rollback de um comando já enviado a uma fechadura não é garantido. Sagas ou compensação podem ser necessárias.

Lotes grandes podem ser aceitos com HTTP 202 e um `job_id`. O cliente consulta o status ou recebe webhook. O servidor processa em segundo plano, grava progresso e resultados por item. Isso evita timeout de uma requisição de minutos. O job precisa de expiração, cancelamento e idempotência. Uploads podem usar arquivo CSV, NDJSON ou objeto em storage. Em plataforma IoT, atualizar firmware de 10 mil dispositivos é um job, não uma chamada síncrona. O resultado deve distinguir agendado, enviado, aplicado e falho. A API precisa limitar concorrência para não saturar gateways. O cliente não deve reenviar todo o lote por um timeout sem consultar o job.