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



  • Sem rótulos