Considerações Iniciais
Os princípios de REST não definem regras claras sobre operações em lote, entretanto é possível implementá-las sem que a API deixe de ser RESTFul.
É preciso entender que a intenção é que toda API seja orientada a trabalhar com um determinado recurso, e dependendo do cenário pode ser vantajoso não implementar o lote.
A melhor solução para esse design vai depender do caso de uso.
É verdade que o lote reduz a quantidade de chamadas ao server, economizando no trafego de rede, e essa é sua grande vantagem de uso (Chamar um mesmo endpoint 300 vezes dentro de um "FOR" não é uma solução muito elegante).
É preciso colocar essa questão numa balança, visto que existem certas desvantagens:
- É mais difícil de monitorar
- É uma operação pouco intuitiva para o client, exigindo que ele conheça melhor sobre o funcionamento da sua API
Quando existir a obrigatoriedade de operações síncronas, evite trabalhar com lote. A tendência é a de que seja um processamento mais demorado, aumentando a chance da perda do pacote e timeout.
Se a intenção é garantir uma transação, em que tudo é processado ou nada é processado, o lote pode resolver. Entretanto, também é possível atingir o mesmo de outra maneira: transações de compensação. Um exemplo básico: 5 chamadas de POST em um endpoint, que cria um determinado recurso. Uma das chamadas retornou o erro 400 na response. O client ao receber essa resposta, trataria de executar o DELETE dos outros recursos que tinham sido inseridos com sucesso antes que um deles apresentasse problemas.
Importante!
Entre em contato com a equipe de Framework TTALK antes de realizar essa modelagem
Padrões e Regras
São permitidas operações de lote através dos verbos POST e DELETE.
Não é permitido realizar lote através de PUT.
O corpo da requisição deve ser um objeto com uma propriedade "items". Essa propriedade é um array com o lote da entidade.
Request:
POST https://.../products { "items": [ { } ] }
Exemplos de response:
Todos os items foram criados
201 Created { "items": [ { } ] }
Items foram criados, atualizados ou deletados
200 Ok { "items": [ { } ] }
Alguns items funcionaram de acordo com o esperado, enquanto outros apresentaram erro
207 Multistatus { "items": [ { } ], "_messages" : [ { "code": "400", "message":"O produto XXX não pode ser incluido. O campo XPTO possui um valor invalido", "detailedMessage": "{ item da lista errado }" } ] }