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.
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
}"
}
]
}